🧙 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

./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

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

./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 installs core; it never touches core source

---

🌍 Portability

Commit your project. On any machine:

git clone <your-project-repo>
cd my-project
./start.sh   # wizard re-runs if core missing; image builds on first run