aicp-claude-agent

Claude Conductor Agent (CCA) --- local CLI wrapper that connects Claude Code to the AICP backend via WebSocket.

What It Does

CCA runs on your local machine alongside Claude Code. It:

1. Executes prompts via the Claude Agent SDK (@anthropic-ai/claude-agent-sdk).
2. Opens a persistent WebSocket connection to the AICP backend (aicp-app).
3. Authenticates using an API key generated in the AICP web UI.
4. Registers as an agent for a specific project.
5. Receives execute_prompt commands from the backend and executes them via the SDK.
6. Streams Claude Code output back to the backend in real time.
7. Reports execution completion with token usage, cost, and duration stats.

Prerequisites

• Node.js 22+
• Claude Code CLI installed and accessible as claude in your PATH
• A running AICP backend (aicp-app)
• An API key generated from the AICP web UI (Avatar > API Keys)

Setup

npm install
npm run dev -- --setup

The interactive setup prompts for:

| Step | Description | Saved to | |------|-------------|----------| | Backend URL | WebSocket URL (e.g., ws://localhost:8080/ws) | ~/.aicp/config.json | | Machine name | Label for this agent (defaults to hostname) | ~/.aicp/config.json | | API key | Paste from AICP web UI, must start with aicp_ | ~/.aicp/config.json | | Project | Select from list fetched via authenticated API | .aicp/aicp.json (local dir) |

Running

# Development
npm run dev

# Development with bypassed permission checks
npm run dev -- --dangerously-skip-permissions

# Production
npm run build
npm start

Configuration

Config Files

| File | Scope | Contains | |------|-------|----------| | ~/.aicp/config.json | Global (all projects) | backend_url, machine_name, api_key | | .aicp/aicp.json | Per-directory (project) | project_id |

The agent searches up the directory tree for .aicp/aicp.json (or legacy .aicp.json), so you can place it at your repo root.

Environment Variables

Environment variables override config file values:

| Variable | Config file key | Description | |----------|----------------|-------------| | BACKEND_WS_URL | backend_url | WebSocket URL to AICP backend | | MACHINE_NAME | machine_name | Agent machine label | | AICP_API_KEY | api_key | API key for authentication | | PROJECT_ID | project_id | Project to register with | | AGENT_ID | --- | Override agent UUID (auto-generated if not set) |

Create a .env.local file for local development:

BACKEND_WS_URL=ws://localhost:8080/ws
AICP_API_KEY=aicp_your_key_here
PROJECT_ID=your_project_id

Architecture

┌──────────────────────────────────────────────────┐
│  aicp-claude-agent                               │
│                                                  │
│  ┌──────────┐     ┌──────────────┐              │
│  │ index.ts │────>│   main.ts    │              │
│  │ (entry)  │     │ (orchestrator)│              │
│  └──────────┘     └──────┬───────┘              │
│                     │         │                  │
│              ┌──────┴──┐  ┌──┴───────────┐      │
│              │ claude/  │  │  websocket/  │      │
│              │ sdk.ts   │  │  client.ts   │      │
│              │ (SDK)    │  │  (WS conn)   │      │
│              └──────────┘  └──────────────┘      │
│                  │                │               │
│           Claude Agent       AICP Backend        │
│              SDK            (WebSocket)           │
└──────────────────────────────────────────────────┘

Source Files

| File | Purpose | |------|---------| | src/index.ts | Entry point — loads dotenv, routes to --setup or main | | src/main.ts | Orchestrator — SDK↔WS bridge, execution lifecycle, terminal UI | | src/config.ts | Config loading — merges env vars, global config, local config | | src/setup.ts | Interactive setup wizard | | src/history.ts | Persistent input history | | src/claude/sdk.ts | Claude Agent SDK — execute prompts, list sessions | | src/commands/index.ts | Slash command dispatcher (/help, /resume) | | src/commands/resume.ts | /resume command — resume previous sessions | | src/terminal/prompt.ts | Styled readline prompt, banner, status bar | | src/terminal/spinner.ts | Animated execution spinner with tool/token info | | src/websocket/client.ts | WebSocket client — connect, reconnect, heartbeat, send/receive | | src/types/protocol.ts | Strict TypeScript types for the WS protocol |

WebSocket Protocol

Agent -> Backend

| Message | Fields | When | |---------|--------|------| | register | agent_id, project_id, machine_name | On connect | | heartbeat | --- | Every 10 seconds | | status | status (idle/busy/offline) | On state change | | message | session_id, role, content, timestamp | During execution | | execution_complete | prompt_id, session_id, token_usage?, cost_usd?, num_turns?, duration_ms? | When execution finishes | | local_prompt | text | When user types a prompt locally |

Backend -> Agent

| Message | Fields | When | |---------|--------|------| | registered | agent_id | After successful registration | | heartbeat_ack | --- | In response to heartbeat | | execute_prompt | prompt_id, session_id, text | When user clicks Execute in the UI | | error | error | On any server-side error |

Agent States

| State | Description | |-------|-------------| | idle | Connected, waiting for work. Only state where new prompts are accepted. | | busy | Executing a prompt. New execute requests are ignored (no queueing). | | offline | Disconnected. Auto-reconnects with exponential backoff (1s to 30s). |

Part of AICP

This repo is one of three that make up AICP:

| Repo | Purpose | |------|---------| | aicp-app | Web application (Fastify backend + React frontend) | | aicp-infra | Terraform infrastructure (Cloud Run, Firestore, IAM) | | aicp-claude-agent | This repo — CLI agent wrapping Claude Code |