Skip to content

claude-coder

The overview of claude-coder: what it is, why it exists, and where to start.

claude-coder is a TypeScript wrapper that drives Claude Code as a human over your Claude subscription. It manages a named, multi-session fleet (each session is one Claude Code conversation) over two transports — the Agent SDK and a real PTY that types into the actual TUI. You reach the fleet through a CLI, an interactive TUI, and a loopback API gateway. Every auth, environment, keystroke, and secret path is fail-closed: the wrapper refuses to act on anything it cannot structurally verify.

Why

  • Subscription-funded automation. Sessions run on your Claude (Max/Pro) subscription via claude OAuth — the same login you already use.
  • Never an API key. A profile that sets ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, or AWS_BEARER_TOKEN_BEDROCK is rejected, and the SDK auth source is checked on the first init message before any user prompt is billed. There is no path that bills an explicit key.
  • Safe within ToS. Driving happens through the same surfaces a human uses: the SDK and the real TUI. Keystrokes are injected only into a TUI whose version and on-screen structure both verify; on any drift the session latches inert. See security for the full model.

Subscription OAuth only

Auth is always your subscription, established with claude /login. claude-coder never accepts an API key. If a credential env var is in force, any command that may spawn claude (repl/resume/fork/tui/serve-api) fails closed; run doctor to check (doctor flags the credential as a failing auth check rather than refusing to run).

At a glance

Capability What it is Learn more
Transports Two ways to drive one session: the Claude Agent SDK, or a real PTY that types into the live TUI concepts
CLI repl, list, resume, fork, history, doctor (plus tui and serve-api, in the rows below) CLI
TUI Interactive multi-session terminal UI over the whole fleet (claude-coder tui) TUI
Local API gateway Loopback server speaking the Anthropic Messages API, backed by your subscription (claude-coder serve-api) — point an Anthropic-SDK app at it in dev with no code changes serve-api
Profiles + secrets Named profiles pick transport, cwd, model, and MCP; secrets resolve at session start and are redacted from events profiles, secrets

The only built-in profile is claude-code-expert (SDK transport, no MCP):

NAME                TRANSPORT  CWD  MODEL  PERMISSION
claude-code-expert  sdk        -    -      -

Requirements

Node >= 22 (ESM). PTY profiles also need a claude binary whose --version is in [2.1.0, 2.2.0); SDK profiles do not. The package ships a single bin: claude-coder.

Start here

Read these three pages in order:

  1. Installation — install, build, and verify with doctor.
  2. Quickstart — run your first turn, then open the TUI.
  3. Concepts — fleet, sessions, transports, profiles, and the fail-closed posture.

From there, the guides cover each surface in depth: CLI, TUI, profiles, secrets, the local API gateway, and the library API. For the safety guarantees, see security; when something goes wrong, see troubleshooting.