Installation

How to install claude-coder from source and verify your setup with doctor.

Prerequisites

Requirement	Detail
Node.js >= 22	The project is pure ESM. Older Node will not run it.
A claude binary	claude --version must be in the band [2.1.0, 2.2.0) (>= 2.1.0, < 2.2.0). Needed for PTY profiles.
A subscription session	Authenticate claude with your Claude Max/Pro account via /login OAuth. Not an API key.

Node

node --version    # must be v22.x or higher

Claude binary

Install the claude CLI and confirm its version is in band:

claude --version    # must be >= 2.1.0 and < 2.2.0

Pinned version band

claude-coder drives claude through a captured terminal grammar that is tied to a specific CLI build. The band is enforced at PTY transport start (assertSupportedVersion fails closed on an out-of-band version). The PTY transport also disables the in-CLI auto-updater (DISABLE_AUTOUPDATER=1) to keep you on a supported build.

Subscription authentication

claude-coder runs on your subscription OAuth session, the same one the claude CLI uses. Log in once:

claude        # then run /login and complete the OAuth flow

To confirm you are on a subscription OAuth session (the same check doctor and the auth preflight point you to):

claude auth status    # confirm you are on subscription OAuth

API-key and backend-redirect credentials are rejected, not just ignored. If any of these env vars is set in your shell, the subscription-auth preflight trips when you run a command that spawns claude (and the SDK transport asserts it again at session init), and doctor reports auth as failed:

ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, AWS_BEARER_TOKEN_BEDROCK, CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, CLAUDE_CODE_USE_FOUNDRY.

A credential var present in your shell does not fail profile/config creation — doctor still reports config as passed. A separate guard rejects a credential var SET inside a profile's config.env (or config.settings.env): that is caught at profile compile and surfaces as a failed config check. These are two different mechanisms; don't conflate them.

Note

The subscription token is injected by the runtime at session start, never by a profile. See security for the full credential model.

Install from npm (recommended)

The package is published as @ahmed-hobeishy/claude-coder (the unscoped claude-coder npm name belongs to an unrelated project). The bin is plain claude-coder:

npm install -g @ahmed-hobeishy/claude-coder
claude-coder doctor

Alternatives that pin a tagged build straight from the repo:

From the release tarballAs a git dependency

Each GitHub release attaches a prebuilt npm pack tarball (dist/ included — nothing to build):

gh release download v0.2.0 -R ahmedEid1/claude-coder -p '*.tgz'
npm install -g ./ahmed-hobeishy-claude-coder-0.2.0.tgz
claude-coder doctor

npm clones the tag, installs dev deps, and runs prepare — which builds dist/ — before packing it into your project:

npm install github:ahmedEid1/claude-coder#v0.2.0
npx claude-coder doctor

Personal use only

claude-coder is an unofficial community project (not affiliated with Anthropic). Your install runs on your claude subscription login. Don't redistribute it as a hosted or multi-user service — that is outside what the subscription is licensed for. See security.

From source (development)

git clone https://github.com/ahmedEid1/claude-coder.git
cd claude-coder
npm install
npm run build

npm run build runs tsc -p tsconfig.build.json and compiles src/ to dist/. This produces the single binary declared in package.json:

Bin	Path
claude-coder	dist/cli/main.js

After a source build the bin entry is not on your PATH automatically.

Running the claude-coder command

Every example in these docs uses the bare claude-coder command. A global tarball install (above) puts it on your PATH directly. From source, run npm link once in the repo (symlinks the bin globally) — or substitute node dist/cli/main.js for claude-coder in any example; the CLI entrypoint has a shebang and runs straight from dist/.

Verify with doctor

doctor is a pure-read setup verifier. It never spawns claude, never spends, and never needs auth beyond reading env vars. It exits 0 on pass/warn and 1 only if a check fails.

claude-coder doctor

Real output:

✓ auth            subscription OAuth (no billed credential in force)
✓ config          no profiles file (built-ins only)
✓ git-hooks       no .githooks/pre-commit in this repo (nothing to activate)

✓ overall: pass

Glyphs: ✓ pass, ⚠ warn, ✗ fail. Each check:

Check	What it verifies
auth	No billed credential env var is in force, so you are on subscription OAuth. Fails if one is set.
config	Your profiles file loads (or there is none, so built-ins are used). Fails if it is named-but-missing or malformed. The only built-in profile is claude-code-expert.
git-hooks	If this repo ships a .githooks/pre-commit secret-leak guard, reports whether it is active (core.hooksPath=.githooks). Advisory (never fails).

A pass overall means you are ready to go. A warn is also fine to start. For machine-readable output, add --json. To validate a specific profiles file, pass --config <path> after the command — the config check loads that file:

claude-coder doctor --config ./my-profiles.json

--config must come after doctor, not before it. The router treats the first argument as the command word, so --config ./my-profiles.json doctor fails with unknown command '--config'.

---

Next: quickstart.