Karamelmar ab7b777ced Add handover doc, update README with Option B architecture

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>

2026-03-09 13:45:37 +01:00

5.1 KiB

Raw Blame History

🧙 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

./wizard.sh

The wizard guides you through:

🔧 Core setup — clones context-studio-core to ~/.context-studio/core/ (once, shared)
📝 Project name & location
⚙️ Workflow — generate from scratch or clone an existing repo
🤖 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
✅ Done — project created, git repo initialized

Preset	Agents
`minimal`	5 agents: coordinator · 2× coder · researcher · tester
`standard`	9 agents: 2× coordinator · 3× coder · 2× researcher · tester · reviewer

⚠️ First ./start.sh builds the container image. Expect 5–15 min. Subsequent starts are instant.

▶️ Starting your project

cd ~/Projects/my-project
./start.sh

This will:

Build the container image if not yet built (first run: 5–15 min)
Start the Podman container (agents run here as your user, not root)
Launch the Context Studio Electron UI
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:

Checks the agents container is running
Relays the call into the container via podman exec
Passes the working directory (falling back to project root if cwd isn't mounted)
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 installs it

🌍 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

5.1 KiB Raw Blame History Unescape Escape