{"_id":"@ahmed-hobeishy/claude-coder","name":"@ahmed-hobeishy/claude-coder","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@ahmed-hobeishy/claude-coder","version":"0.2.0","description":"Drive Claude Code as a human: a subscription-funded fleet of named sessions over SDK + PTY transports, with a CLI, a multi-session TUI, and a loopback Anthropic-Messages API gateway (serve-api).","keywords":["claude","claude-code","anthropic","agent","fleet","session-manager","tui","cli","subscription","anthropic-messages-api"],"homepage":"https://claude-coder-docs.pages.dev/","bugs":{"url":"https://github.com/ahmedEid1/claude-coder/issues"},"repository":{"type":"git","url":"git+https://github.com/ahmedEid1/claude-coder.git"},"license":"MIT","type":"module","engines":{"node":">=22"},"bin":{"claude-coder":"dist/cli/main.js"},"main":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"publishConfig":{"access":"public"},"scripts":{"build":"tsc -p tsconfig.build.json","prepare":"node scripts/install-git-hooks.mjs || true && npm run build","prepublishOnly":"npm run build","typecheck":"tsc -p tsconfig.json --noEmit","lint":"eslint .","lint:fix":"eslint . --fix","format":"prettier --write .","format:check":"prettier --check .","test":"vitest run","test:unit":"vitest run --project unit","test:types":"vitest run --project types","test:watch":"vitest","test:cov":"vitest run --coverage","check":"npm run typecheck && npm run lint && npm run format:check && npm run test:cov"},"dependencies":{"@anthropic-ai/claude-agent-sdk":"0.3.158","@xterm/headless":"^6.0.0","node-pty":"^1.1.0","zod":"4.4.3"},"devDependencies":{"@eslint/js":"^9","@types/node":"^22","@vitest/coverage-v8":"^3","eslint":"^9","eslint-config-prettier":"^10","expect-type":"^1.1","prettier":"^3","typescript":"^5.7","typescript-eslint":"^8","vitest":"^3"},"types":"./dist/index.d.ts","_id":"@ahmed-hobeishy/claude-coder@0.2.0","_integrity":"sha512-xVWdh4J551xu74Rt4UtBU20FqmDsLsMRQf3+XrpEDm8A6b74PL7BsloKWBSyDF5Us9h22fKZMi/B16KHtSsoRw==","_resolved":"/home/ubuntu/projects/claude-coder/ahmed-hobeishy-claude-coder-0.2.0.tgz","_from":"file:ahmed-hobeishy-claude-coder-0.2.0.tgz","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-xVWdh4J551xu74Rt4UtBU20FqmDsLsMRQf3+XrpEDm8A6b74PL7BsloKWBSyDF5Us9h22fKZMi/B16KHtSsoRw==","shasum":"20f51ada011b17b970416410ffb8c971e7659155","tarball":"https://registry.npmjs.org/@ahmed-hobeishy/claude-coder/-/claude-coder-0.2.0.tgz","fileCount":404,"unpackedSize":2087222,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIA/6Q1He1ZgWt+Sez/kg6q7gqA+IF8gBcCTNYihIGDQpAiEArjs56mFR4D/GRTg0UzUsafmx2+/XgpJ2VTWQvIbrcCQ="}]},"_npmUser":{"name":"ahmed-hobeishy","email":"ahmedhobeishy.tools@gmail.com"},"directories":{},"maintainers":[{"name":"ahmed-hobeishy","email":"ahmedhobeishy.tools@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/claude-coder_0.2.0_1780691670617_0.43090947844448"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-05T20:34:30.437Z","0.2.0":"2026-06-05T20:34:30.789Z","modified":"2026-06-05T20:34:30.993Z"},"maintainers":[{"name":"ahmed-hobeishy","email":"ahmedhobeishy.tools@gmail.com"}],"description":"Drive Claude Code as a human: a subscription-funded fleet of named sessions over SDK + PTY transports, with a CLI, a multi-session TUI, and a loopback Anthropic-Messages API gateway (serve-api).","homepage":"https://claude-coder-docs.pages.dev/","keywords":["claude","claude-code","anthropic","agent","fleet","session-manager","tui","cli","subscription","anthropic-messages-api"],"repository":{"type":"git","url":"git+https://github.com/ahmedEid1/claude-coder.git"},"bugs":{"url":"https://github.com/ahmedEid1/claude-coder/issues"},"license":"MIT","readme":"# claude-coder\n\n[](https://github.com/ahmedEid1/claude-coder/actions/workflows/ci.yml)\n[](https://www.npmjs.com/package/@ahmed-hobeishy/claude-coder)\n[](https://claude-coder-docs.pages.dev/)\n\nDrive [Claude Code](https://claude.com/claude-code) **as a human** โ funded by your\nClaude **Max/Pro subscription**, not a metered API key. `claude-coder` is a TypeScript\nlibrary + CLI that manages a fleet of named, differently-configured Claude Code sessions\nacross two backends, with a scriptable control plane and an interactive multi-session TUI.\n\n**๐ Full documentation: **\n\n> **Unofficial.** This is an independent community project, not affiliated with or endorsed\n> by Anthropic. It drives **your own** Claude Code login on **your own** machine โ keep your\n> usage within [Anthropic's terms](https://www.anthropic.com/legal/consumer-terms): personal\n> tooling, not a hosted or multi-user service (the `serve-api` gateway is loopback-only by\n> construction for exactly this reason).\n\n> **Subscription, not API key.** Every turn runs against your logged-in Claude Code OAuth\n> session. `claude-coder` is **fail-closed**: it refuses to start a session if\n> `ANTHROPIC_API_KEY` (or another billed-credential env var) is in force, so you can never\n> accidentally bill an API account. See [Authentication](#authentication).\n\n---\n\n## What it gives you\n\n- **A managed fleet of named sessions.** Define profiles (cwd, model, permission mode,\n allowed tools, MCP servers, transport) and create/resume/fork named sessions against\n them, capped and queued so you never overload your subscription.\n- **Two backends, one contract.** An **SDK** transport (the\n `@anthropic-ai/claude-agent-sdk`, structured events) and a **PTY** transport (drives the\n real `claude` TUI over a pseudo-terminal via `node-pty`). Both honor one\n capability-graded `SessionConfig`.\n- **An interactive TUI** (`claude-coder tui`) โ a hand-rolled, zero-dependency,\n multi-session manager: a live session list, streaming transcripts, inline permission\n approval, interrupt, persistence/resume/fork, scrollback + search, and a `?` help overlay.\n- **A scriptable control plane** โ the `FleetApi` facade (used by the CLI and TUI) is a\n serializable-shaped, in-process API over the whole fleet; see `examples/drive-fleet.ts`.\n\n---\n\n## Requirements\n\n- **Node.js >= 22**\n- **A logged-in Claude Code subscription.** Install the Claude Code CLI and run `claude`\n once to authenticate (OAuth). `claude-coder` reuses that session.\n- The **PTY** transport additionally needs the `claude` binary on your `PATH`.\n\n## Install\n\nFrom npm (the package is scoped; the bin is plain `claude-coder`):\n\n```bash\nnpm install -g @ahmed-hobeishy/claude-coder\nclaude-coder doctor # pure-read setup check (no spend)\n```\n\nOr from source (development):\n\n```bash\ngit clone https://github.com/ahmedEid1/claude-coder\ncd claude-coder\nnpm install # `prepare` compiles dist/\nnode dist/cli/main.js --help\n```\n\nMore options (release tarballs, git-tag installs):\n[installation guide](https://claude-coder-docs.pages.dev/getting-started/installation/).\n\n---\n\n## Authentication\n\n`claude-coder` only drives Claude **inference** through your subscription OAuth session\n(`apiKeySource โ {oauth, none}`). It performs an **auth preflight** before any command that\ncould spawn `claude` and **throws** if a billed credential is present in the environment โ\nthe deny set includes `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`, and `AWS_BEARER_TOKEN_BEDROCK`.\nIf you see an auth error, unset those variables; you should be relying on the Claude Code\nlogin, not an API key.\n\n---\n\n## Configuration: profiles\n\nA **profile** is a named, reusable session configuration. Profiles are loaded from the first\nof:\n\n1. `--config ` (explicit), else\n2. `./claude-coder.config.json` (project-local), else\n3. `~/.claude/claude-coder/profiles.json` (the documented default).\n\nThe file is a JSON array of profiles:\n\n```json\n[\n { \"name\": \"work\", \"transport\": \"sdk\", \"cwd\": \"/home/me/project\" },\n {\n \"name\": \"review\",\n \"transport\": \"sdk\",\n \"cwd\": \"/home/me/project\",\n \"permissionMode\": \"default\",\n \"model\": \"claude-opus-4-8\"\n },\n { \"name\": \"tui-driver\", \"transport\": \"pty\", \"cwd\": \"/home/me/project\" }\n]\n```\n\nCommon per-profile fields: `name` (required), `transport` (`\"sdk\"` | `\"pty\"`, required),\n`cwd`, `model`, `permissionMode` (`\"default\"` | `\"acceptEdits\"` | `\"plan\"` |\n`\"bypassPermissions\"`), `allowedTools` / `disallowedTools`, and `mcpConfig`. Credentials and\nsecrets are **never** read from the config file.\n\nThere is also a built-in profile, **`claude-code-expert`** (SDK transport, no MCP) โ the\ndefault profile that is always available, so the CLI and TUI work with no config file.\n\n---\n\n## CLI\n\n```\nclaude-coder [args]\n\n repl interactive multi-turn loop over a session (Ctrl-C interrupts, exit closes)\n list list persisted + live-this-process sessions\n resume reattach a persisted session (run a turn if a prompt is given)\n fork branch a persisted session under a new name\n history read a session's transcript history\n tui open the interactive multi-session TUI over the fleet\n doctor verify your setup (subscription auth, config, git-hooks) โ read-only\n serve-api run a loopback HTTP server (Anthropic Messages API wire format) for local dev โ subscription-backed\n\nGlobal flags: --config --verbose --help --version\n```\n\n### Examples\n\n```bash\n# Interactive multi-turn REPL over a session created from a profile\nnode dist/cli/main.js repl work\n\n# Persisted sessions: list, resume with a follow-up (--json for the full result + cost), fork\nnode dist/cli/main.js list\nnode dist/cli/main.js resume work \"now add a test\"\nnode dist/cli/main.js resume work \"say hi\" --json\nnode dist/cli/main.js fork work --name work-experiment\n```\n\n---\n\n## The TUI\n\n```bash\nnode dist/cli/main.js tui --config ./claude-coder.config.json\n```\n\nA persistent left session list, the focused session's streaming transcript, and a\nmode-aware status/help bar. Press **`?`** at any time for the full, always-accurate keymap.\nThe essentials:\n\n| Key | Action |\n| ---------------------------- | ------------------------------------------------------------- |\n| `n` | new session (pick a profile, name it) |\n| `e` / `Enter` | edit / send a turn to the focused session |\n| `i` | interrupt a busy turn |\n| `Tab` / `โ` `โ` / `1`โ`9` | move focus across sessions |\n| `r` / `f` | resume / fork the focused persisted session |\n| `c` | cancel a queued create |\n| `PgUp` `PgDn` / `Home` `End` | scroll the transcript (pins; `End` re-follows) |\n| `/`, then `n` / `N` | search the transcript, next / prev match |\n| `a` / `d` / `s` | on a permission prompt: allow once / deny / allow for session |\n| `?` | help overlay |\n| `q` / `Ctrl-C` | quit (graceful teardown, no orphaned `claude`) |\n\nAt the hard fleet cap (2 live sessions) a 3rd create surfaces as a **queued** row and is\nadmitted FIFO when a slot frees. Permission requests appear inline; informative rate-limit\nheartbeats are silent (only real pressure notifies).\n\n---\n\n## Architecture\n\n```\nTransport (SDK + PTY, one capability-graded contract)\n โ Orchestration (profiles ยท admission/queue ยท persistence ยท secrets ยท failover ยท FleetApi)\n โ CLI (repl/list/resume/fork/history/tui/doctor/serve-api)\n โ TUI (pure Elm-style reducer + pure renderer + thin controller + impure driver)\n```\n\nThe TUI is split into a **pure reducer** (`reduce(state, msg) โ {state, effects}` +\n`project(state) โ ViewModel`), a **pure renderer** (`ViewModel โ string[]`), a thin\n**controller** (mailbox, owns one `FleetApi`), and an impure **driver** (raw terminal) โ so\nnearly all of it is unit-tested deterministically.\n\n---\n\n## Development\n\n```bash\nnpm run build # tsc โ dist/\nnpm run check # typecheck + eslint + prettier --check + vitest --coverage (the gate)\nnpm test # vitest run\n```\n\nThe default gate spends no money, needs no auth, and spawns no real `claude`. The live\nend-to-end smokes are **spend-gated** behind `CC_LIVE=1` and live under `test/tui/**` /\n`scripts/live-e2e/` (never collected by the default gate).\n\n---\n\n## Status & scope\n\nThe Transport, Orchestration, CLI, and TUI layers are implemented and\nlive-validated on a real Max subscription. Use within Anthropic's terms of service for\nClaude Code; `claude-coder` automates an interactive client you are entitled to use โ it does\nnot circumvent authentication or billing.\n\n## License\n\n[MIT](./LICENSE) ยฉ Ahmed\n","readmeFilename":"README.md","_rev":"1-9e136ee323a872b2c7de8c545e8c4982"}