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>
This commit is contained in:
parent
16c0053d68
commit
ab7b777ced
2 changed files with 155 additions and 37 deletions
108
README.md
108
README.md
|
|
@ -6,18 +6,40 @@
|
|||
|
||||
## ✨ What it does
|
||||
|
||||
One command. One conversation. A complete project drops out:
|
||||
One command. A complete project drops out:
|
||||
|
||||
```
|
||||
~/.context-studio/core/ ← 🔧 installed once, shared globally
|
||||
|
||||
~/projects/my-project/
|
||||
├── .devcontainer/ ← 🐳 Node 22 · Rust · Claude Code · Electron deps
|
||||
~/Projects/my-project/
|
||||
├── .devcontainer/ ← 🐳 Node 22 · Rust · Claude Code
|
||||
├── workflow/ ← 🤖 agents, roles, A2A config, project docs
|
||||
└── src/ ← 💻 your code
|
||||
├── 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
|
||||
```
|
||||
|
||||
Open in devcontainer → start Context Studio → talk to your agent team.
|
||||
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)
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -32,8 +54,6 @@ Open in devcontainer → start Context Studio → talk to your agent team.
|
|||
|
||||
**Auto-install supported on:** Arch · Debian/Ubuntu · RHEL/Fedora · openSUSE
|
||||
|
||||
> The wizard detects your distro and installs `git` and `podman`/`docker` automatically if they are missing. SSH key and API key must be set up by you.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Usage
|
||||
|
|
@ -44,57 +64,50 @@ Open in devcontainer → start Context Studio → talk to your agent team.
|
|||
|
||||
The wizard guides you through:
|
||||
|
||||
1. 🔧 **Core setup** — clones `context-studio-core` to `~/.context-studio/core/` (once)
|
||||
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` | 🎯 coordinator · 2× coder · researcher · tester |
|
||||
| `standard` | 🎯🎯 2× coordinator · 3× coder · 2× researcher · tester · reviewer |
|
||||
| `minimal` | 5 agents: coordinator · 2× coder · researcher · tester |
|
||||
| `standard` | 9 agents: 2× coordinator · 3× coder · 2× researcher · tester · reviewer |
|
||||
|
||||
5. ✅ **Done** — git repo initialized, devcontainer ready
|
||||
5. ✅ **Done** — project created, git repo initialized
|
||||
|
||||
> ⚠️ **First `./start.sh`** builds the container image. Expect 5–15 min. Subsequent starts are instant.
|
||||
|
||||
---
|
||||
|
||||
## 📂 Open the project
|
||||
## ▶️ Starting your project
|
||||
|
||||
**🖥️ VS Code**
|
||||
```bash
|
||||
code ~/projects/my-project # → "Reopen in Container"
|
||||
cd ~/Projects/my-project
|
||||
./start.sh
|
||||
```
|
||||
|
||||
**⌨️ CLI**
|
||||
```bash
|
||||
cd ~/projects/my-project
|
||||
docker build -t my-project .devcontainer/
|
||||
docker run -it --rm \
|
||||
-v "$(pwd)":/workspace \
|
||||
-v "$HOME/.context-studio/core":/opt/context-studio/core \
|
||||
-e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
|
||||
my-project bash
|
||||
```
|
||||
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
|
||||
|
||||
**▶️ Start Context Studio** _(inside container)_
|
||||
```bash
|
||||
node $CS_CORE_DIR/core/start.js # Electron UI
|
||||
node $CS_CORE_DIR/core/start.js --ui-mode=headless # servers only
|
||||
./stop.sh # force-stop container without closing the UI
|
||||
./update.sh # update core, claude-code inside container, OS packages
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌍 Mobility
|
||||
## 🔄 How `bin/claude` works
|
||||
|
||||
Commit your project. On any machine:
|
||||
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:
|
||||
|
||||
```bash
|
||||
git clone <your-project-repo>
|
||||
cd my-project
|
||||
code . # done
|
||||
```
|
||||
|
||||
> Core is re-cloned automatically on first run. Only `ANTHROPIC_API_KEY` is needed on the host.
|
||||
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**
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -103,10 +116,12 @@ code . # done
|
|||
```
|
||||
🧙 wizard.sh ← entry point
|
||||
📁 lib/
|
||||
utils.sh ← prompts, colors, helpers
|
||||
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
|
||||
|
|
@ -116,3 +131,22 @@ code . # done
|
|||
📁 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
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue