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

1. Configure your .npmrc to use the GitLab Package Registry:

# Project-level .npmrc (recommended) — or add to ~/.npmrc for global config
@carealytix:registry=https://gitlab.com/api/v4/projects/<PROJECT_ID>/packages/npm/
//gitlab.com/api/v4/projects/<PROJECT_ID>/packages/npm/:_authToken=<YOUR_TOKEN>

Replace <PROJECT_ID> with the GitLab project ID and <YOUR_TOKEN> with a personal access token (scope: read_api) or deploy token.

2. Install globally:

npm install -g @carealytix/codewalkers

This makes the cw CLI available globally.

Alternative: Install from source

git clone git@gitlab.com:carealytix/tools/codewalkers.git && cd codewalkers
npm install
npm run build
npm link

Initialize a workspace

cd your-project
cw init

Creates a .cwrc config file marking the workspace root.

Register a project

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

Add a provider account

# 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

cw --server

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

Create an initiative and start working

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

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

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.

Documentation

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