Frequently Asked Questions

Coderrr is a real agent loop, so what matters most is how well a model handles multi-turn tool use — not its coding benchmark score.

• Best results: Anthropic Claude, or GPT-4o via OpenAI. Both are reliable at long tool-calling sequences.
• Free, out of the box: the default — gemma4:31b-cloud via Ollama, tool-capable on a free Ollama account.
• Fully offline: qwen2.5-coder:14b locally. It works, but is noticeably weaker at the multi-turn tool use the loop depends on.
• Many models, one key: OpenRouter.

Details in Providers.

Your key never leaves your machine except to go to your provider.

• Stored in your OS keyring when the keyring extra is installed
• Otherwise in ~/.coderrr/config.toml, created mode 0600 — owner-only from the moment it exists, not chmod-ed afterwards
• Sent directly to the provider you configured
• Masked in every command that prints configuration

v1 POSTed keys to a hosted backend. v2 has no backend — see Migrating from v1.

Yes. Ollama is the default provider and needs no key. Local models need no account at all:

ollama pull qwen2.5-coder:14b
coderrr config       # select Ollama, then the model
coderrr run "..."

With a fully local Ollama model, yes — inference is local. One caveat: skill retrieval reaches out to the registry, so the agent simply finds no skills when offline. It still plans and implements without them.

No. The write tools are absent from the model's tool list during planning — it is not asked to refrain from editing, it has no tool that edits. Your approval is what unlocks them.

Two things change that: --yes skips the approval prompt (a spec is still written and must contain tasks), and [agent].confirm_writes = true goes the other way and prompts on every individual write. See Spec-Driven Flow.

Not against your working tree — there is no tool that does that. Commands run in a sandbox: a throwaway copy of the project by default, a container with --network=none and all capabilities dropped when Docker is available.

The scratch tier limits blast radius but is not a security boundary against deliberately hostile code. coderrr doctor tells you which tier is active; Sandbox explains the difference.

Never. v1 had an --auto-commit flag that ran git add . and swept unrelated work into its commits. v2 leaves version control entirely to you — which also means git diff and git revert work normally as your undo.

Commit .coderrr/specs/ — it is project documentation, and reads well in a pull request next to the diff it produced. The generated .coderrr/.gitignore already excludes the transient cache/ and session/ directories.

Yes, and this is the intended workflow. The plan is files on disk, already written when Coderrr stops to ask. Rewrite a task, fix the file list, delete the two tasks you did not want — execution reads what is on disk.

Declining costs nothing either: the spec stays, and you can edit it and re-run to continue from there.

That depends entirely on your provider and model — Coderrr adds no fee of its own. Token counts print at the end of every run so you can calibrate:

tokens: 48210 in / 6114 out

Two levers if runs feel expensive: point [verify].model at something cheap so verification is not billed at your main model's rate, and lower [agent].max_iter so a stubborn task retries less.

Three ceilings, all configurable:

• [agent].max_tool_turns — 50 tool calls per task attempt
• [agent].max_iter — 5 retries per task after a failure
• [agent].max_seconds — 30 minutes of wall clock per attempt

Ctrl-C also works: in a session it cancels the current task and returns you to the prompt; in a one-shot run it exits with code 130 and reports that nothing further was modified.

The agent records why in tasks.md. Read it with coderrr spec show, fix whatever it hit — a missing dependency, an ambiguous requirement — and re-run. The spec is the memory, so the next run picks up where this one stopped rather than starting over.

No. Without it, the scratch tier is used and everything works. Install Docker if you want commands run under real filesystem and network isolation.

No to both. coderrr-cli on npm is deprecated, and the hosted backend is retired — v2 is a single Python CLI that talks to providers directly. Migrating from v1 has the full mapping.

coderrr config                  # change provider, model, or key
coderrr run "..." -m gpt-4o     # override for one run
coderrr                         # then /model gpt-4o for the session

A /model change applies to that session only and is not saved.