Getting Started

Coderrr is a free, open-source CLI coding agent that plans before it edits. It writes a spec, shows it to you, and stops — nothing on disk changes until you approve.

Install

pipx install coderrr          # or: uv tool install coderrr

Coderrr v2 is a Python package on PyPI and needs Python 3.10 or newer. No provider SDKs are required — every provider is reached over plain HTTP.

Pick a provider

coderrr config

An interactive prompt walks you through five providers:

• Ollama — the default. Local or Ollama-hosted models, no API key needed.
• Anthropic — Claude
• OpenAI — GPT
• Google — Gemini
• OpenRouter — many models behind one key

Keys stay on your machine. They go to the OS keyring when available, otherwise to ~/.coderrr/config.toml written mode 0600. Nothing is proxied through a server.

Run your first change

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

Coderrr reads your code, writes requirements.md, design.md and tasks.md into .coderrr/specs/NNN-slug/, then shows you the plan and waits. You can edit those files before approving to steer the work.

Once you approve, it implements the plan task by task, running the code in a sandbox to check its own work.

Or start an interactive session

coderrr

A bare coderrr opens a REPL with persistent history and slash commands. Each turn runs the full plan → approve → implement flow and returns you to the prompt.

Next steps

• Spec-Driven Flow — what the approval gate actually enforces
• Providers — models, keys, and which ones handle tool use well
• Sandbox — where the agent runs commands, and what that does and does not contain
• CLI Reference — every command and flag