Quickstart¶
Drive your first Claude Code session in about five steps.
This page assumes you have a Claude Max or Pro subscription and have already installed claude-coder. Auth is always your subscription via claude OAuth — never an API key.
1. Check your setup¶
doctor runs three read-only checks (auth, config, and git-hooks). It never spawns claude and never spends.
✓ 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
Exit code is 0 when everything passes or warns, 1 if any check fails. A warn is fine to start.
Warning
If auth fails, you have a billed credential in your environment. claude-coder rejects billed credentials such as ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, and AWS_BEARER_TOKEN_BEDROCK (among others — see security). Unset them and sign in with claude instead.
2. Pick a profile¶
A profile names a transport and its settings. One profile is always built in, even with no config file: claude-code-expert, which uses the SDK transport with no MCP server attached. Use it for everything below. To define your own, see profiles.
3. Hold a conversation¶
repl creates a session from a profile and keeps it open across many turns. Type a line, press Enter, and the turn runs. Type exit (or send EOF with Ctrl-D) to close.
what is a session?
status: completed
A session is a single live conversation with Claude Code...
cost: $0.0011 (session $0.0011)
tokens: in 95 / out 64
exit
(example output — exact text, cost, and tokens vary per turn)
The first and last lines above (what is a session? and exit) are what you type; the rest is printed by each turn. While a turn is running, Ctrl-C interrupts it without closing the session; a second Ctrl-C closes and exits.
Note
This step spends from your subscription and needs live auth. Pass --cwd <dir> to set the working directory for the session.
4. Drive the multi-session TUI¶
For an interactive terminal UI over several sessions at once, run:
See TUI for the full keymap and layout.
Sessions persist¶
A repl session is ephemeral, but named sessions survive. List what exists and reattach later:
claude-coder list # live + persisted sessions
claude-coder resume my-session "continue" # reattach, optionally run a turn
claude-coder resume my-session --json # raw TurnResult instead of human output
resume with no prompt just prints the session state.