Karamelmar
7c9b61bfce
- start.sh: auto-register project in ~/.config/context-studio/projects/ before launching Electron — without this acquireProjectLock() silently skips writing the lock file, waitForServers() never finds the registry port, all agent ports stay null (localhost:null errors) - start.sh: mount all known Claude Code credential locations into container (~/.claude/.credentials.json, ~/.claude.json, $CLAUDE_CONFIG_DIR variants) not just ~/.anthropic which was empty on this system - bin/claude: create /tmp/cs-ready-<agentId> on host after 3s delay so CS Core's CLI ready marker poll resolves instead of timing out after 10s - workflow.sh: add hasTrustDialogAccepted:true to all agent settings.json so claude goes straight to priming without the folder trust dialog - prereqs.sh: add ensure_api_key() — checks all credential locations, prompts with masked input if none found, offers to save to shell profile - wizard.sh: trap SIGINT for graceful abort — gum confirm popup, reverts created project dir and cloned core dir, leaves installed packages untouched - core.sh: set _WIZARD_CORE_CLONED=true before clone for cleanup tracking - electron-config.js: increase serverStartupTimeout 30s→90s (config file in core/config/, not source — safe to edit) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
174 lines
6.2 KiB
Markdown
174 lines
6.2 KiB
Markdown
# 🧙 Context Studio Wizard
|
||
|
||
> Scaffold a fully configured multi-agent AI development environment in seconds.
|
||
|
||
---
|
||
|
||
## ✨ What it does
|
||
|
||
One command. A complete project drops out:
|
||
|
||
```
|
||
~/.context-studio/core/ ← 🔧 installed once, shared globally
|
||
|
||
~/Projects/my-project/
|
||
├── .devcontainer/ ← 🐳 Node 22 · Rust · Claude Code
|
||
├── workflow/ ← 🤖 agents, roles, A2A config, project docs
|
||
├── src/ ← 💻 your code
|
||
├── bin/claude ← 🔀 wrapper: routes claude → container
|
||
├── start.sh ← ▶️ start container + Context Studio UI
|
||
├── stop.sh ← ⏹️ stop the agents container
|
||
└── update.sh ← 🔄 update core, claude-code, OS packages
|
||
```
|
||
|
||
Run `./start.sh` → Podman container starts → Electron UI opens → agents prime automatically → talk to your team.
|
||
|
||
---
|
||
|
||
## 🏗️ Architecture (Option B)
|
||
|
||
```
|
||
HOST CONTAINER (cs-<project>)
|
||
───────────────────────────── ────────────────────────
|
||
Context Studio Core (Electron) Claude Code binary
|
||
A2A agent servers (node) ←─── bin/claude wrapper routes
|
||
Electron UI every claude call here
|
||
workflow management mounted at same abs path
|
||
```
|
||
|
||
- **CS Core + all agent servers** run on the host (no display issues, native Electron)
|
||
- **Claude Code binary** runs inside the Podman container as the current user (not root)
|
||
- **`bin/claude`** is prepended to PATH so CS Core's server process finds it automatically
|
||
- **Paths match** host ↔ container (project mounted at the same absolute path)
|
||
|
||
---
|
||
|
||
## 📋 Prerequisites
|
||
|
||
| | Tool | Notes |
|
||
|---|------|---------|
|
||
| 🔀 | `git` | Auto-installed if missing |
|
||
| 🐳 | `podman` _(preferred)_ or `docker` | Auto-installed if missing |
|
||
| 🔑 | SSH key → `github.com` | Must be set up manually |
|
||
| 🗝️ | Anthropic credentials | API key or `claude auth login` — wizard checks automatically |
|
||
|
||
**Auto-install supported on:** Arch · Debian/Ubuntu · RHEL/Fedora · openSUSE
|
||
|
||
---
|
||
|
||
## 🚀 Usage
|
||
|
||
```bash
|
||
./wizard.sh
|
||
```
|
||
|
||
The wizard guides you through:
|
||
|
||
1. 🔧 **Prerequisites** — checks git, podman/docker, Anthropic credentials
|
||
2. 🔧 **Core setup** — clones `context-studio-core` to `~/.context-studio/core/` (once, shared)
|
||
3. 📝 **Project name & location**
|
||
4. ⚙️ **Workflow** — generate from scratch _or_ clone an existing repo
|
||
5. 🤖 **Agent preset** _(if generating)_
|
||
|
||
| Preset | Agents |
|
||
|--------|--------|
|
||
| `minimal` | 5 agents: coordinator · 2× coder · researcher · tester |
|
||
| `standard` | 9 agents: 2× coordinator · 3× coder · 2× researcher · tester · reviewer |
|
||
|
||
6. ✅ **Done** — project created, git repo initialized
|
||
|
||
**Ctrl+C at any point** → confirmation prompt → reverts all created files (installed packages kept).
|
||
|
||
> ⚠️ **First `./start.sh`** builds the container image. Expect 5–15 min. Subsequent starts are instant.
|
||
|
||
---
|
||
|
||
## 🔑 Anthropic credentials
|
||
|
||
The wizard checks for credentials in this order:
|
||
|
||
1. `ANTHROPIC_API_KEY` environment variable
|
||
2. `~/.claude/.credentials.json` (default `claude auth login` location)
|
||
3. `~/.claude.json`
|
||
4. `$CLAUDE_CONFIG_DIR/.credentials.json` / `$CLAUDE_CONFIG_DIR/.claude.json`
|
||
5. `~/.anthropic/.credentials.json`
|
||
|
||
If none found, you're prompted to enter an API key (masked input) with an option to save it to `~/.zshrc` / `~/.bashrc`.
|
||
|
||
All credential files that exist are **mounted read-only** into the container so Claude Code can authenticate.
|
||
|
||
---
|
||
|
||
## ▶️ Starting your project
|
||
|
||
```bash
|
||
cd ~/Projects/my-project
|
||
./start.sh
|
||
```
|
||
|
||
This will:
|
||
1. Build the container image if not yet built (first run: 5–15 min)
|
||
2. Start the Podman container (agents run inside as your user, not root)
|
||
3. Register the project with Context Studio (required for server startup)
|
||
4. Launch the Context Studio Electron UI
|
||
5. Agents start, prime automatically — no trust dialogs, no manual steps
|
||
6. When you close the UI → container is stopped automatically
|
||
|
||
```bash
|
||
./stop.sh # force-stop container without closing the UI
|
||
./update.sh # update core, claude-code inside container, OS packages
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 How `bin/claude` works
|
||
|
||
CS Core on the host needs to call `claude`. Instead of using the host's `claude`, `start.sh` prepends `bin/claude` to `PATH`. This wrapper:
|
||
|
||
1. Checks the agents container is running
|
||
2. Relays the call into the container via `podman exec`
|
||
3. Falls back to project root as workdir if cwd isn't mounted in the container
|
||
4. Creates the CS Core ready marker (`/tmp/cs-ready-<agentId>`) after 3s so `/prime` injection isn't delayed
|
||
|
||
---
|
||
|
||
## 🗂️ Repository layout
|
||
|
||
```
|
||
🧙 wizard.sh ← entry point
|
||
📁 lib/
|
||
utils.sh ← prompts, colors, gum helpers
|
||
prereqs.sh ← auto-install git + podman/docker + API key check
|
||
core.sh ← global core install/update
|
||
project.sh ← devcontainer + project scaffold
|
||
workflow.sh ← generate or clone workflow config
|
||
container.sh ← generates start/stop/update/bin/claude
|
||
📁 templates/
|
||
Dockerfile ← Node 22 + Rust + build tools + Claude Code
|
||
devcontainer.json ← mounts, env vars, VS Code extensions
|
||
agents-minimal.json ← 5-agent preset
|
||
agents-standard.json ← 9-agent preset
|
||
system.json ← A2A server defaults
|
||
📁 roles/ ← coordinator, coder, researcher, tester, reviewer
|
||
📁 hooks/rules/ ← per-role tool restrictions
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ Hard rules
|
||
|
||
- **`~/.context-studio/core/` source is READ-ONLY** — never modify source files, commit, or push to it
|
||
- `~/.context-studio/core/config/electron-config.js` is a config file — safe to edit (e.g. timeouts)
|
||
- The wizard only clones and `npm install`s core; it never touches core source
|
||
|
||
---
|
||
|
||
## 🌍 Portability
|
||
|
||
Commit your project. On any machine:
|
||
|
||
```bash
|
||
git clone <your-project-repo>
|
||
cd my-project
|
||
./start.sh # wizard re-runs if core missing; image builds on first run
|
||
```
|