@a9650615/claude-acp-kit

Generic Claude ACP (Agent Client Protocol) library — batteries-included primitives so a new agent project can ship in minutes instead of weeks.

Status: 0.1.0 – pre-release. API surface is stabilizing; expect minor breakages until 1.0.

Why

Every Claude agent needs the same plumbing: JSON-RPC framing over stdio, session lifecycle, permission flow, credential detection, usage tracking, MCP supervision, structured logging. This library packages all of that with strict types and zero magic, so your project only writes the parts that are actually unique.

Features

| Feature | What it does | | ------------------------- | --------------------------------------------------------------------- | | AcpServer | NDJSON JSON-RPC dispatch loop with typed handlers | | Sessions | Lifecycle, persistence, mode switching, cancellation | | Auth detector | Reads ~/.claude/.credentials.json, watches mtime, sniffs 401s | | Login helper | Shells to claude /login and waits for refreshed creds | | Usage tracker | Wraps ccusage for session/daily/monthly; in-process token counter | | Budget gate | Per-session caps + alert hooks | | Permissions | allow_once / allow_always / reject_* policy + audit log | | Tools registry | Zod-validated tool definitions, typed executor | | MCP supervisor | Spawn, restart, health-check stdio MCP servers | | Backoff/retry | Exponential w/ jitter for 429/529 | | Cancellation | Propagates session/cancel to in-flight work | | Logger | pino-based, session_id correlation | | Heartbeat | Health checks + auto-reconnect |

Install

npm install @a9650615/claude-acp-kit
# optional: enable ccusage integration
npm install ccusage

Try it without installing

npx @a9650615/claude-acp-kit doctor                                    # environment check
npx @a9650615/claude-acp-kit init my-agent && cd my-agent && npm i     # scaffold an agent
npx @a9650615/claude-acp-kit usage daily --since 2026-01-01            # ccusage report
npx @a9650615/claude-acp-kit skills list                               # discover ~/.claude/skills
npx @a9650615/claude-acp-kit serve ./agent.ts                          # run an agent file

Subcommands documented in src/cli/README.md.

Quickstart

import { AcpServer, Transport, createLogger } from "@a9650615/claude-acp-kit";

const { StdioTransport } = Transport;

const logger = createLogger({ level: "info" });
const transport = new StdioTransport({ logger });

const server = new AcpServer({
  transport,
  logger,
  agent: {
    async prompt(ctx, params) {
      ctx.emit({
        sessionUpdate: "agent_message_chunk",
        content: { type: "text", text: "hello!" },
      });
      return { stopReason: "end_turn" };
    },
  },
});

await server.start();

This matches examples/minimal-agent verbatim (modulo the relative imports we use to build pre-publish). See examples/ for the full set, including a richer agent wired with usage tracking, budget gating, permissions, and a tool registry.

Documentation

| For | Read | | --- | --- | | First-time setup | docs/GETTING_STARTED.md | | Per-feature usage | docs/USAGE.md | | Copy-paste patterns | docs/RECIPES.md | | Common gotchas | docs/FAQ.md | | Git flow + agent handoff | docs/GIT_FLOW.md | | Module architecture | ARCHITECTURE.md | | Each module's API | src/<module>/README.md |

Architecture

See ARCHITECTURE.md for module boundaries, interface contracts, and ADRs.

For agents (human or AI) working on this repo

Read AGENTS.md first. It is the canonical rule sheet for module ownership, the non-contamination contract, the git/npm boundaries, and the documentation duties. A pre-commit import guard (scripts/check-imports.mjs) enforces module boundaries mechanically.

Project layout

acp_base_lib/
├── src/
│   ├── server.ts             # AcpServer dispatch
│   ├── transport/            # stdio NDJSON JSON-RPC
│   ├── protocol/             # wire types + zod schemas
│   ├── session/              # session lifecycle
│   ├── auth/                 # cred detect + login
│   ├── usage/                # ccusage + tracker
│   ├── tools/                # registry + executor
│   ├── permissions/          # gate + policy
│   ├── mcp/                  # MCP child-process supervisor
│   ├── logging/              # pino logger
│   ├── errors/               # normalized JSON-RPC errors
│   ├── utils/                # backoff, cancellation, events
│   └── config/               # env + file loader
├── examples/
├── docs/
│   ├── adr/                  # architectural decision records
│   └── work-log/             # per-module dev journals
└── .github/workflows/        # CI + release

Development

npm install
npm run typecheck
npm run lint
npm run test
npm run build

Per-module work logs

Every module owner appends to docs/work-log/<module>.md when shipping work. Captures intent, tradeoffs, and follow-ups. Don't skip — that log is how a future contributor (or you in six months) understands a non-obvious choice.

Contributing

Read CONTRIBUTING.md. Conventional commits enforced via lefthook. Releases via changesets.

License

MIT