Karamelmar
ab7b777ced
README: rewritten to reflect actual Option B architecture (Electron on host, agents in container), correct start.sh usage, bin/claude routing, and portability. Remove outdated manual docker run instructions. HANDOVER.md: documents all fixes made this session, what is unverified, what still needs testing (claude-code check, localhost:null, network), and key architecture facts for the next session. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
152 lines
5.1 KiB
Markdown
152 lines
5.1 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 → talk to your agent team.
|
||
|
||
---
|
||
|
||
## 🏗️ Architecture (Option B)
|
||
|
||
```
|
||
HOST CONTAINER (cs-<project>)
|
||
───────────────────────────── ────────────────────────
|
||
Context Studio Core (Electron) ←─── All Claude Code agents
|
||
starts A2A servers mounted at same abs path
|
||
opens Electron UI bin/claude wrapper routes
|
||
manages workflow every claude call here
|
||
```
|
||
|
||
- **CS Core** runs on the host (Electron UI, no display issues)
|
||
- **All agents** run 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_API_KEY` | Must be set in your environment |
|
||
|
||
**Auto-install supported on:** Arch · Debian/Ubuntu · RHEL/Fedora · openSUSE
|
||
|
||
---
|
||
|
||
## 🚀 Usage
|
||
|
||
```bash
|
||
./wizard.sh
|
||
```
|
||
|
||
The wizard guides you through:
|
||
|
||
1. 🔧 **Core setup** — clones `context-studio-core` to `~/.context-studio/core/` (once, shared)
|
||
2. 📝 **Project name & location**
|
||
3. ⚙️ **Workflow** — generate from scratch _or_ clone an existing repo
|
||
4. 🤖 **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 |
|
||
|
||
5. ✅ **Done** — project created, git repo initialized
|
||
|
||
> ⚠️ **First `./start.sh`** builds the container image. Expect 5–15 min. Subsequent starts are instant.
|
||
|
||
---
|
||
|
||
## ▶️ 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 here as your user, not root)
|
||
3. Launch the Context Studio Electron UI
|
||
4. 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. Passes the working directory (falling back to project root if cwd isn't mounted)
|
||
4. All agents — including the main coordinator — run **inside the container**
|
||
|
||
---
|
||
|
||
## 🗂️ Repository layout
|
||
|
||
```
|
||
🧙 wizard.sh ← entry point
|
||
📁 lib/
|
||
utils.sh ← prompts, colors, gum helpers
|
||
prereqs.sh ← auto-install git + podman/docker
|
||
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` is READ-ONLY** — never modify, commit, or push to it
|
||
- It is a shared global dependency; the wizard only clones and `npm install`s it
|
||
|
||
---
|
||
|
||
## 🌍 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
|
||
```
|