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