Configuration

Location#

The directory is created on first run.

Configuration is global, not per-repository. Conversation history is the one thing scoped to where you are working: it lives under sessions/<project>/<session-id>.json, keyed by the repository root. See Sessions & history.

providers.json#

{  "defaultProvider": "google",  "selectedModel": "gemini-3.6-flash",  "approvalMode": "auto-read-only",  "retentionDays": 30,  "providers": {    "google": { "type": "api", "apiKey": "..." }  }}

Unrecognised keys are preserved when Woopcode rewrites the file, so anything you add by hand survives.

Editing it by hand#

You can, and Woopcode will read it. The safer path for the values that have a command is to use the command, because it validates: woopcode providers login verifies a key before saving it, and /approval cannot write a mode that does not exist.

An approval mode the parser does not recognise falls back to the default rather than being treated as permissive. An unreadable setting must not be able to widen what runs without asking.

When the file is corrupt#

A providers.json or a session file that is not valid JSON — a truncated write, a bad hand edit — is moved aside rather than crashing every command that touches it:

Could not read provider config (invalid JSON). Moved it to~/.config/woopcode/providers.json.corrupt-1785508675645 and started fromdefaults.

Your broken copy is kept under that .corrupt-<timestamp> name; the next launch starts clean.

Retired providers#

A provider that an earlier version offered and Woopcode has since dropped is removed from your config on startup — but only if it has no key stored. An entry with a key is left alone: deleting a credential silently would hide something you may want to remove yourself.

Environment#

Location#

Credentials#

Woopcode reads an API key from the environment when one is present, and prefers it over the stored config. This is what lets it run somewhere with no writable home directory and no terminal to run setup in — a CI job, a benchmark container built fresh for every trial.

They are checked in this order, and the first one set wins:

An unusable provider is treated differently depending on which variable named it. WOOPCODE_API_KEY with WOOPCODE_PROVIDER is an instruction addressed to Woopcode, so naming a provider it has no client for is an error at startup rather than a failure on the first turn. A vendor variable is not an instruction — ANTHROPIC_API_KEY is usually exported for some other tool sharing the shell — so an unusable one is skipped and the search continues to the next, or to the stored config.

Behaviour#

A value that is not a positive integer is ignored with a warning on stderr, and the default is used. An unreadable setting never silently changes behaviour.

WOOPCODE_THINKING_BUDGET#

Takes off, -1 (automatic, the default), or a token count. The three providers accept different things, so the same value does not mean the same thing everywhere — and a number is never faked into a budget the provider did not apply.

Only Gemini takes a token count. Current Claude models reject an explicit budget, and OpenAI takes an effort level rather than a number, so on both a count falls back to letting the model decide — which is what -1 already meant. On Gemini, budgets below roughly a thousand are ignored by the model rather than honoured.

See also#

• Configuring providers — the task, not the schema
• Sessions & history — what a session holds, and how to resume one

Added in woopcode@0.6.0