@coralai/claude-code-agent

Status: v0.1.0-alpha.0 (skeleton, Phase 1 Step 1.2 of extraction plan) Full API spec: /home/coral/projects/claude-code-agent/README.md (vision doc) CEO plan: ~/.gstack/projects/claude-code-agent/ceo-plans/2026-05-14-acp-runtime-v1.md

Lean runtime primitive for embedding ACP-compatible agents (Claude Code) in Node.js apps.

import { ClaudeCodeAgent } from '@coralai/claude-code-agent';

const agent = new ClaudeCodeAgent({ cwd: '/path/to/project' });
await agent.start();
const handle = agent.prompt('Reply with OK');
const result = await handle.result;
console.log(result.text);   // "OK"
await agent.stop();

📅 Status

| Item | Status | |---|---| | Package skeleton | ✅ Step 1.2 done | | Code extraction from sps-cli | ⏳ Step 1.3 | | New API implementation | ⏳ Step 1.4 (PromptHandle / fork / promptJson / recording / OTel / elicitation hook) | | sps-cli use this package | ⏳ Step 1.5 | | Regression gates | ⏳ Step 1.6 | | First publish to npm | ⏳ Step 1.7 (as v0.1.0) |

Do not import this package yet — src/ is intentionally empty until Step 1.4.

Module layout (per CEO plan D2 decision)

src/
  index.ts              ← public API barrel
  agent.ts              ← ClaudeCodeAgent main class (~300 lines target)
  prompt-handle.ts      ← PromptHandle + queue logic (~200 lines)
  hooks/                ← default fs / terminal / permission / elicitation impls (~250)
  recording/            ← session jsonl writer + replayer (~250)
  telemetry/            ← OpenTelemetry adapter (~150)
  errors.ts             ← AgentError + 18 codes (~50)
  internal/             ← capability negotiation + state machine + transport wiring (~150)

Target total: ~1000-1300 lines of TypeScript.

Hard prerequisites (runtime)

For consumers once v0.1.0 ships:

| Dependency | Install | |---|---| | Node.js ≥ 18 | (ESM-only) | | claude CLI binary | curl -fsSL https://claude.ai/install.sh \| bash | | claude-agent-acp shim | npm install -g @agentclientprotocol/claude-agent-acp@^0.33 | | Anthropic auth | claude reads $ANTHROPIC_API_KEY or ~/.claude/.credentials.json; this package does not manage auth |

⚠️ Production embedding: must explicitly set permissionMode: 'readonly' or 'manual'; default 'auto' is dev-only.

Decisions in effect (from review pipeline)

| Decision | Source | |---|---| | Package name stays @coralai/claude-code-agent for v1 (no rename to acp-runtime) | codex outside voice + CEO reversal 1 | | prompt() returns PromptHandle, not Promise<PromptResult> | codex finding #4/#5 + Eng D1 | | PromptHandle.updates is broadcast (buffer-all, multi-consumer) | Eng D1 | | fork() no-args (forks current session) | codex finding #7 | | warmup() removed → start({ eager: true }) | codex finding #6 | | 6-module layout (this README §Module layout) | Eng D2 | | Recording fixtures: manual generation + nightly live verify | Eng D3 | | Recording write: async batch (100ms / 64KB flush) | Eng D4 | | OTel attribute: truncate @ 8KB + truncated: true flag | Eng D4 | | onElicitation hook reserved but dormant (shim 0.33.1 doesn't fire) | Elicitation spike 2026-05-14 | | Hook signature uses SDK native schema.CreateElicitationRequest/Response | spike |

Why this package exists

sps-cli currently embeds ~5000 lines of ACP/session/worker management code directly. This package extracts that into a reusable primitive:

• 90% of code reuse from sps-cli's providers/ + manager/ + relevant core/
• Captures spawn race / orphan recovery / marker file lessons learned the hard way
• Forward-compatible with codex/gemini ACP agents (v1.1 expansion)
• Forward-compatible with elicitation (when shim wires it up)

After v1, sps-cli depends on this package instead of carrying its own ACP implementation.

Links

• Full vision doc (851 lines, all decisions): /home/coral/projects/claude-code-agent/README.md
• CEO plan with cross-model reversals: ~/.gstack/projects/claude-code-agent/ceo-plans/2026-05-14-acp-runtime-v1.md
• Test plan: ~/.gstack/projects/claude-code-agent/coral-main-eng-review-test-plan-*.md
• Elicitation spike data: ~/.gstack/projects/claude-code-agent/elicitation-spike-results-*.json
• Spike code: /home/coral/projects/claude-code-agent/spike/spike.ts

v0.1.0-alpha.0 · skeleton · 2026-05-14