ai-workflow/CLAUDE.md

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

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

cd dashboard && npm install && npm run dev
cd dashboard && npm run build

Dashboard dev mode proxies /api to http://localhost:3000.

Container Launch

./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:

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