Usage

Two ways in: a one-shot run, or an interactive session. Both take the same route — plan, approve, implement.

One-shot run

cd my-project
coderrr run "add rate limiting to the API"

Coderrr plans, shows you the plan, and waits. Approve and it implements; decline and nothing was modified — the spec is still saved, so you can edit it and re-run.

The exit code is 0 when the run succeeded, 1 when it failed, and 130 if you interrupted it with Ctrl-C.

Interactive session

cd my-project
coderrr

   ██████╗ ██████╗ ██████╗ ███████╗██████╗ ██████╗ ██████╗
  ██╔════╝██╔═══██╗██╔══██╗██╔════╝██╔══██╗██╔══██╗██╔══██╗
  ██║     ██║   ██║██║  ██║█████╗  ██████╔╝██████╔╝██████╔╝
  ██║     ██║   ██║██║  ██║██╔══╝  ██╔══██╗██╔══██╗██╔══██╗
  ╚██████╗╚██████╔╝██████╔╝███████╗██║  ██║██║  ██║██║  ██║
   ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝

  v2.0.0  anthropic/claude-sonnet-4-20250514  sandbox: docker
  ~/code/my-project

  Type a request, or /help for commands.

coderrr ❯ _

Each turn runs the complete flow and returns you to the prompt. It is a line-oriented REPL, not a full-screen TUI — diffs, tool output, and plans stay in your scrollback and can be scrolled, copied, and piped like any other command output.

Input comes from prompt_toolkit: persistent history across sessions, arrow-key recall, and readline editing.

Slash commands

Command	What it does
/help	The command list
/spec	Show the most recent spec
/specs	List every spec in this project with task progress
/model [name]	Show the current model, or switch it for this session. Not saved — use coderrr config to persist.
/auto	Toggle skipping the approval prompt. Warns loudly when turning it on.
/config	Provider, model, endpoint, masked key, sandbox tier, verify mode
/doctor	Environment check
/clear	Clear the screen and reprint the banner
/exit	Leave the session (or Ctrl-D)

Ctrl-C cancels the task in progress and returns you to the prompt rather than exiting — a mistyped request does not cost you the whole session.

What a run looks like

─────────────────────────── Planning ───────────────────────────
◇ sandbox: docker — container; filesystem and network isolated
  ⚙ tree
  ⚙ read_file  src/api/routes.py
  ⚙ search_skills  rate limiting
  ⚙ create_spec  add-rate-limiting
  ⚙ write_spec  requirements
  ⚙ write_spec  design
  ⚙ write_spec  tasks
  ⚙ finish

──────────────────── Plan — 003-add-rate-limiting ────────────────────
# Requirements: Add rate limiting to the API
...

───────────────────────────── Tasks ─────────────────────────────
  #  Task                              Files
  1  Add a token-bucket limiter        src/api/limiter.py
  2  Wire the limiter into the router  src/api/routes.py
  3  Cover burst and refill            tests/test_limiter.py

◇ Spec written to .coderrr/specs/003-add-rate-limiting/ — edit it before approving if needed.

Approve this plan and let Coderrr edit 3 task(s) worth of files? [y/N]: y

────────────────────────── Execution ──────────────────────────
  ⚙ update_task  1 in_progress
  ⚙ write_file  src/api/limiter.py
    ■ write_file  42 lines
  ⚙ run_in_sandbox  pytest tests/test_limiter.py
    ■ run_in_sandbox  exit 0 in 2.4s
  ⚙ update_task  1 done
  ...

─────────────────────────── Summary ───────────────────────────
■ All 3 task(s) complete.
tokens: 48210 in / 6114 out

Tool calls are shown as they happen. Every write is preceded by a diff, so you see the change before it lands.

Skipping the approval prompt

coderrr run "..." --yes    # or -y
coderrr --yes              # session starts with auto-approve on

Use with care

A spec is still written and must contain tasks before execution starts, but you will not see the plan before files change. Reserve this for changes you would have approved unread.

Working outside the current directory

coderrr run "fix the flaky test" -d ../other-repo
coderrr -d ~/code/api

The workspace root is also the containment boundary — the agent cannot read or write outside it, and symlinks pointing out are resolved and rejected.

Scripting

printf 'add a health check endpoint\n/exit\n' | coderrr --yes

Piped input falls back to plain reads instead of prompt_toolkit, so transcripts stay clean. For CI, set the key via environment variable and pass --yes.

Reviewing past work

coderrr spec list           # every spec, with task progress
coderrr spec show           # the most recent one
coderrr spec show 003       # by number, name, or slug

Specs are the agent's memory across sessions — see Spec-Driven Flow.

Example requests

coderrr run "add a REST endpoint for blog posts with CRUD operations"
coderrr run "refactor the auth module to use JWT tokens"
coderrr run "fix the database connection timeout on cold start"
coderrr run "add unit tests for the user service"
coderrr run "migrate the config loader from JSON to TOML"

Requests that are questions rather than changes work too — the agent plans, you decline the plan, and you keep the written analysis.