95 lines
3.0 KiB
Markdown
95 lines
3.0 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code when working with this repository.
|
|
|
|
## What This Is
|
|
|
|
Multi-agent AI orchestration system. The active V2 model is leader/worker based: the host-side `leader` talks to the user and orchestrates work, while per-chain `worker` runtimes execute tasks in isolated worktrees and containers.
|
|
|
|
## Key Commands
|
|
|
|
### Inbox CLI
|
|
|
|
```bash
|
|
cd inbox && go build -o /tmp/inbox-host ./cmd/inbox
|
|
export INBOX_WORKSPACE=/Users/xd/project/ai-workflow-v2
|
|
|
|
/tmp/inbox-host server --workspaces-dir /Users/xd/project/ai-workflow-v2/inbox-worktrees --port 3000
|
|
/tmp/inbox-host api GET /api/v2/projects
|
|
/tmp/inbox-host api POST /api/v2/topics --data '{"workspace_id":"ws_1","title":"Signup Flow","space":"workflow","status":"execution"}'
|
|
```
|
|
|
|
### Dashboard
|
|
|
|
```bash
|
|
cd dashboard && npm install && npm run dev
|
|
cd dashboard && npm run build
|
|
```
|
|
|
|
Dashboard dev mode proxies `/api` to `http://localhost:3000`.
|
|
|
|
### Container Launch
|
|
|
|
```bash
|
|
./inbox/launch.sh <project-dir> [workspace-slug]
|
|
# Example: ./inbox/launch.sh apps/phonesite phonesite-main
|
|
```
|
|
|
|
The host Inbox API must already be running. `launch.sh` registers the `project` / `workspace` in SQLite, creates a git worktree, launches the Podman container, and starts `inbox agent` in API mode.
|
|
|
|
## Runtime Model
|
|
|
|
Runtime ownership is split as:
|
|
|
|
- `project`: long-lived source project such as `apps/blog`
|
|
- `workspace`: per-run git worktree / container instance such as `inbox-worktrees/blog-main`
|
|
|
|
Persistent runtime state is stored in SQLite, not in worktree files:
|
|
|
|
```text
|
|
<repo>/.runtime/inbox.db
|
|
<repo>/inbox-worktrees/<workspace>/
|
|
/tmp/inbox-codex-*
|
|
```
|
|
|
|
Container agents must use:
|
|
|
|
- `INBOX_API_URL`
|
|
- `INBOX_WORKSPACE_NAME`
|
|
|
|
This keeps worktrees code-only and prevents `.runtime` or `.inbox-meta.json` from being written into them.
|
|
|
|
## Message Flow
|
|
|
|
Messages are authored as Markdown with YAML front matter, but persisted in SQLite:
|
|
|
|
1. `inbox send` stores the message body and metadata in SQLite and marks mailbox state
|
|
2. `inbox agent --role <role>` polls inbox state from SQLite or, in container mode, through the host Inbox API
|
|
3. Codex output, sessions, chain/task state, and dispatch live logs are written back to SQLite
|
|
4. Processed messages are archived by mailbox-state update, not by moving files on disk
|
|
|
|
## Roles
|
|
|
|
Roles are DB-backed runtime configuration, not file-backed prompts.
|
|
|
|
- `leader` — host-side orchestrator for user dialogue, chain/task decomposition, and execution control
|
|
- `worker` — per-chain executor inside isolated worktrees/containers
|
|
- `user` — human-only participant; never auto-executed by the AI runtime
|
|
|
|
Legacy fixed roles such as `product`, `backend`, `frontend`, `reviewer`, and discovery roles are not part of the active V2 execution model.
|
|
|
|
## Dashboard
|
|
|
|
`dashboard/` is a React 19 + TypeScript + Vite app that polls the Inbox Web API for:
|
|
|
|
- messages
|
|
- role status
|
|
- executions
|
|
- merge requests
|
|
- workflow board state
|
|
- leader/worker thread activity
|
|
|
|
## Skills
|
|
|
|
Reusable skill definitions live in `config/codex/skills/`.
|