claude-code-driver

Documentation · Getting started · Architecture · API reference · Contributing

Drive the interactive Claude Code TUI (pinned to 2.1.316) from Node.js. The TUI runs inside a private tmux server and you control it with a small typed API: send prompts, answer permission requests, interrupt, change modes, and watch everything Claude does as one stream of events. You keep your subscription login, you get no API billing and no headless -p mode, and the TUI stays fully visible to a human.

import { ClaudeSession } from 'claude-code-driver';

await using session = await ClaudeSession.start({
  cwd: '/path/to/a/trusted/project',
  permissions: (req) => (req.toolName === 'Read' ? { behavior: 'allow' } : { behavior: 'deny', message: 'read-only' }),
});

const turn = session.send('Summarise README.md in one sentence.');
for await (const e of turn) if (e.type === 'text') process.stdout.write(e.data.delta);
const result = await turn.done; // { outcome: 'completed', text, tools, durationMs, ... }

How it works

Claude Code is started in a tmux pane on a private socket (tmux -L ccd-<pid>-<hex>). The library observes it through four independent channels and reconciles them into one state machine:

Channel	What it gives	Source
hooks	prompt acceptance, tool start/end, permission requests, Stop, SessionStart/End, MessageDisplay text	an injected --settings file whose hooks call a loopback HTTP server (or a unix-socket forwarder), running in a worker thread
transcript	the authoritative record: every message, tool result, interrupt marker, turn_duration, API errors	poll + pread tail of ~/.claude/projects/<slug>/<session>.jsonl
screen	dialogs, spinners, retry/stall banners, usage-limit lines, the composer	tmux capture-pane, classified by a versioned profile
network (opt-in)	per-request timing on api.anthropic.com tunnels	a CONNECT pass-through sidecar (no TLS interception)

Input never goes through raw keystrokes: prompts are staged through an $EDITOR shim (Ctrl-G), so a prompt is never mistaken for a slash command, bash mode or a paste. Every submission is acknowledged by the UserPromptSubmit hook (or the transcript) before the turn counts as started. A self-test at startup (a blocked nonce prompt) proves the hook round trip works before the session reports ready.

The code is layered (model → platform → channels → core → session → runtime → api/cli). The core is a pure, deterministic reducer, so a recorded session replays byte for byte. See docs/DESIGN.md.

Requirements

• Node.js ≥ 20 (development tooling: Node 22; .nvmrc)
• tmux ≥ 3.2 (tested with 3.5a), on PATH, in /opt/homebrew/bin, /usr/local/bin or /usr/bin
• Claude Code 2.1.316 (@anthropic-ai/claude-code), logged in with a claude.ai subscription (claude auth status → authMethod: claude.ai). API keys and Bedrock/Vertex/gateway providers are refused on purpose.
• macOS or Linux.
• A trusted working directory (accepted once in the TUI), or trust: 'seed', which writes only that one trust key after inspecting the workspace for risky settings.

Install

The package is not on npm yet. Build it from source and add it to your project as a local dependency:

git clone https://github.com/BlitzJB/claude-code-driver.git
cd claude-code-driver && pnpm install && pnpm build      # Node 22 for the tooling (nvm use)
cd /path/to/your/project
pnpm add /path/to/claude-code-driver @anthropic-ai/[email protected]

The library looks for claude.exe in this order: the claude.bin option, your project's node_modules, its own node_modules, then PATH. The version must be exactly 2.1.316 (claude.expectVersion: 'any' overrides this, at your own risk).

This is the beginning of the README. Read the rest at the original. Read the full README ↗