Codewalkers/README.md

# Codewalkers

Multi-agent workspace for orchestrating multiple AI coding agents working in parallel on a shared codebase.

Codewalkers coordinates agents from different providers (Claude, Codex, Gemini, Cursor, AMP, Auggie, OpenCode) through a unified CLI and web dashboard. It manages the full lifecycle: planning initiatives, decomposing work into phases and tasks, dispatching agents to isolated git worktrees, merging results, and reviewing changes — all from a single `cw` command.

## Key Features

- **Multi-provider agents** — Data-driven provider configs. Add new providers without code changes.
- **Initiative workflow** — Three-level hierarchy (Initiative > Phase > Task) with dependency DAGs and topological ordering.
- **Architect agents** — AI-driven planning: discuss, plan, detail, and refine modes produce structured proposals you accept or dismiss.
- **Git worktree isolation** — Each agent works in its own worktree. No conflicts during parallel execution.
- **Account rotation** — Register multiple provider accounts. On usage-limit exhaustion, automatically fails over to the next available account (LRU scheduling).
- **Two execution modes** — *YOLO* auto-merges everything. *Review-per-phase* adds manual approval gates with inline code review, threaded comments, and diff viewing.
- **Docker preview deployments** — Zero-config preview environments via `.cw-preview.yml`, `docker-compose.yml`, or bare `Dockerfile`. Caddy reverse proxy with health checks.
- **Inter-agent communication** — Agents ask each other questions via a conversation system. Idle agents auto-resume when a question arrives.
- **Chat sessions** — Persistent iterative refinement loops where you send messages and agents apply changes with revertable changesets.
- **Real-time dashboard** — React web UI with live agent output streaming, pipeline visualization, Tiptap page editor, and command palette.
- **Event-driven architecture** — 58+ typed domain events drive all coordination. No polling loops.
- **Cassette testing** — Record/replay agent interactions for full-pipeline E2E tests at zero API cost.

## Getting Started

### Prerequisites

- Node.js 20+
- Git 2.38+ (for `merge-tree --write-tree`)
- Docker (optional, for preview deployments)
- At least one supported AI coding CLI installed (e.g., `claude`, `codex`, `gemini`)

### Install

```sh
git clone <repo-url> && cd codewalk-district
npm install
npm run build
npm link
```

This makes the `cw` CLI available globally.

### Initialize a workspace

```sh
cd your-project
cw init
```

Creates a `.cwrc` config file marking the workspace root.

### Register a project

```sh
cw project register --name my-app --url /path/to/repo
```

### Add a provider account

```sh
# Auto-extract from current Claude login
cw account add

# Or register with a setup token
cw account add --token <token> --email user@example.com
```

### Start the server

```sh
cw --server
```

Starts the coordination server on `localhost:3847`. The web dashboard is served at the same address.

### Create an initiative and start working

```sh
cw initiative create "Add user authentication"
cw architect discuss <initiative-id>
```

From the web dashboard, accept the architect's proposals, approve phases, and dispatch execution.

## Architecture

```
CLI (cw)
  +-- CoordinationServer
        |-- HTTP + tRPC API (70+ procedures)
        |-- EventBus (58 typed events)
        |-- MultiProviderAgentManager
        |     |-- ProcessManager (detached child processes)
        |     |-- WorktreeManager (git worktrees per agent)
        |     |-- OutputHandler (JSONL stream parsing)
        |     +-- LifecycleController (retry, signal recovery)
        |-- DispatchManager (task queue, dependency DAG)
        |-- PhaseDispatchManager (phase queue, topological sort)
        |-- ExecutionOrchestrator (end-to-end coordination)
        |-- PreviewManager (Docker compose, Caddy proxy)
        +-- 14 Repository ports (SQLite/Drizzle adapters)

Web UI (React 19)
  +-- TanStack Router + tRPC React Query
        |-- Initiative management & page editor (Tiptap)
        |-- Pipeline visualization (phase DAG)
        |-- Execution tab (task dispatch, live agent output)
        +-- Review tab (diffs, inline comments, approval)
```

**Monorepo layout:**

| Path | Description |
|------|-------------|
| `apps/server/` | CLI, coordination server, agent management, all backend modules |
| `apps/web/` | React dashboard (Vite + Tailwind + shadcn/ui) |
| `packages/shared/` | Shared TypeScript types between server and web |

**Hexagonal architecture:** Repository ports define data access interfaces. Drizzle/SQLite adapters implement them. Swappable without touching business logic.

## Supported Providers

| Provider | CLI | Resume | Structured Output |
|----------|-----|--------|-------------------|
| Claude | `claude` | `--resume` | Prompt-based |
| Codex | `codex` | `codex resume` | `--output-schema` |
| Gemini | `gemini` | `--resume` | `--output-format` |
| Cursor | `cursor-agent` | — | `--output-format` |
| AMP | `amp` | `--thread` | `--json` |
| Auggie | `aug` | — | — |
| OpenCode | `opencode` | — | `--format` |

Providers are configured as data in `apps/server/agent/providers/presets.ts`. Adding a new provider means adding an entry to the presets object.

## CLI Reference

```
cw --server [-p port]          Start coordination server
cw init                        Initialize workspace (.cwrc)
cw status                      Server health check
cw id [-n count]               Generate nanoid(s) offline

cw agent spawn <prompt> --task <id> [--provider <name>]
cw agent stop|delete|list|get|resume|result <name>

cw initiative create|list|get|phases <name|id>
cw architect discuss|plan|detail|refine <id>

cw phase add-dependency --phase <id> --depends-on <id>
cw phase queue|dispatch|queue-status|dependencies <id>

cw task list|get|status <id>
cw dispatch queue|next|status|complete <id>

cw project register --name <n> --url <u>
cw project list|delete|sync|status [name|id]

cw account add|list|remove|refresh|extract [id]

cw preview start|stop|list|status|setup [id]

cw listen --agent-id <id>
cw ask <question> --from <id> --agent-id <target>
cw answer <response> --conversation-id <id>
```

## Workflow Overview

```
1. Create initiative        cw initiative create "Feature X"
2. Plan with architect      cw architect discuss <id>  -->  plan  -->  detail
3. Accept proposals         (web UI: review & accept phase/task proposals)
4. Approve phases           (web UI: approve phases for execution)
5. Dispatch                 (web UI: queue phases, auto-dispatch tasks to agents)
6. Agents execute           (parallel, isolated worktrees, auto-retry on crash)
7. Review                   (web UI: diff viewer, inline comments, approve/request changes)
8. Merge                    (auto or manual per execution mode)
9. Complete                 (push branch or merge into default branch)
```

**Execution modes:**
- **YOLO** — Phases auto-merge on completion, next phase auto-dispatches. No gates.
- **Review per phase** (default) — Each completed phase pauses for human review. Approve to merge and continue.

## Development

```sh
npm run dev          # Watch mode (server)
npm run dev:web      # Vite dev server (frontend)
npm run build        # TypeScript compilation
npm link             # Link CLI globally after build
```

After any change to server code (`apps/server/**`), run `npm run build && npm link`.

## Testing

```sh
npm test                                    # Unit + E2E (no API cost)
npm test -- <file>                          # Run specific test file

# Record cassettes (one-time API cost)
CW_CASSETTE_RECORD=1 npm test -- <test-file>

# Real provider integration tests (~$0.50)
REAL_CLAUDE_TESTS=1 npm test -- apps/server/test/integration/real-providers/ --test-timeout=300000
```

The **cassette system** records real agent subprocess interactions and replays them deterministically. Full-pipeline E2E tests run at zero API cost after initial recording. See [docs/testing.md](docs/testing.md).

## Documentation

| Topic | Link |
|-------|------|
| Architecture | [docs/architecture.md](docs/architecture.md) |
| Agent lifecycle, providers, accounts | [docs/agent.md](docs/agent.md) |
| Database schema & repositories | [docs/database.md](docs/database.md) |
| Server & tRPC API (70+ procedures) | [docs/server-api.md](docs/server-api.md) |
| Frontend & components | [docs/frontend.md](docs/frontend.md) |
| CLI commands & configuration | [docs/cli-config.md](docs/cli-config.md) |
| Dispatch & events (58 event types) | [docs/dispatch-events.md](docs/dispatch-events.md) |
| Git, process management, logging | [docs/git-process-logging.md](docs/git-process-logging.md) |
| Docker preview deployments | [docs/preview.md](docs/preview.md) |
| Testing & cassette system | [docs/testing.md](docs/testing.md) |
| Database migrations | [docs/database-migrations.md](docs/database-migrations.md) |
| Logging guide | [docs/logging.md](docs/logging.md) |

## Tech Stack

- **Runtime:** Node.js (ESM), TypeScript
- **Database:** SQLite via better-sqlite3 + Drizzle ORM
- **API:** tRPC v11 with SSE subscriptions
- **Frontend:** React 19, TanStack Router, Tailwind CSS, shadcn/ui, Tiptap
- **Process:** execa (detached child processes)
- **Git:** simple-git (worktrees, branches, merges)
- **Logging:** pino (structured JSON)
- **Testing:** vitest