docs / configuration

Configuration

One JSON file at ~/.wombat/config.json, one key at a time from the CLI, and environment variables for the values you do not want on disk.

The file and the commands

wombat config prints the resolved configuration with keys redacted. wombat config set changes one value, validates it, and saves immediately. wombat setup is the guided path for provider, key and model.

wombat config
wombat config set provider anthropic
wombat config set model claude-sonnet-4.5
wombat config set fallback_models claude-haiku-4.5,gpt-5-mini
wombat config set scout_model gpt-5-mini
wombat config set theme gruvbox
wombat config set mode create

Paths. ~/.wombat/config.json holds settings, ~/.wombat/sessions/ holds JSONL transcripts per project, ~/.wombat/mcp-auth/ holds OAuth tokens (mode 0600), and ~/.wombat/agents/ and ~/.wombat/skills/ hold custom agents and skills. WOMBAT_HOME moves the directory, WOMBAT_CONFIG points at a specific file.

Providers

Wombat speaks OpenAI-compatible chat completions, Anthropic, and OpenCode; anything that presents an OpenAI-compatible base URL works, including a gateway in front of a local model. Each provider entry stores its kind, base URL, optional API key and a model list.

wombat config set provider openai
wombat config set model gpt-5
wombat models openai          # list what the provider reports
wombat doctor                 # one small request, with errors surfaced

Keys can also come from the environment (OPENAI_API_KEY, ANTHROPIC_API_KEY, and the variables your gateway expects), which keeps them out of the file. WOMBAT_PROVIDER and WOMBAT_MODEL override the selected provider and model for one process.

Permissions

Permissions are gates on classes of action, not on individual tools. Each gate is allow, ask or deny; an MCP server can hold its own gate that falls back to the global mcp value.

gate	default	covers
`bash`	allow	Shell commands, including `git`.
`write`	allow	Creating files and writing whole files.
`edit`	allow	Editing and patching existing files.
`network`	allow	Fetches and remote calls made by tools.
`mcp`	ask	Every MCP tool, unless overridden per server.
`dangerous`	ask	Commands flagged as destructive.
`sensitive-read`	ask	Credentials, keys and secret files.

wombat config set permissions.bash ask
wombat config set permissions.write ask
wombat config set permissions.mcp allow
wombat config set permissions.mcp:github deny

Defaults are permissive. The shipped config allows shell, write, edit and network so the agent can finish a job without stopping. If you want to be consulted, set the classes you care about to ask before the first run in an unfamiliar repository. --yolo on wombat run auto-approves one run; /yolo toggles the same thing in chat.

Model behaviour

Two settings decide how much of the harness the model sees, and they are the ones that move token cost the most.

wombat config set tool_profile auto       # auto | minimal | coding | web | semantic | verify | media | orchestrator | full
wombat config set research_mode auto      # auto | off | quick | standard | deep
wombat config set capabilities.web auto   # auto | on | off
wombat config set capabilities.semantic off
wombat config set reasoning high          # off | low | medium | high | max

auto inspects the prompt and loads matching capabilities. A task that mentions a page or a screenshot gets web; a rename gets nothing extra. The tools & profiles guide has the full table.

Orchestration limits

The fleet is on by default. These keys cap it; every one of them defaults to a finite value, and token budgets default to unlimited.

key	default	meaning
`orchestrator`	true	Attach the planning and worker tools when the profile allows them.
`max_parallel_scouts`	5	Read-only workers running at once.
`max_parallel_agents`	5	Custom agents running at once.
`max_parallel_writers`	2	Workers that may change files, at once.
`writer_max_steps`	0	Per-run step cap for writers; 0 uses the session default.
`worker_token_budget`	0	Per-worker token cap; 0 is unlimited.
`turn_worker_token_budget`	0	Cap across all workers for one turn.
`review_policy`	always	`always`, `auto` (skips docs-only patches) or `never`.
`check_policy`	auto	Where checks run: `auto`, `worktree`, `merge` or `both`.
`keep_worktrees`	false	Keep worktrees after the run for inspection.

Interface settings

Thinking display and reasoning level are settable from the CLI. Theme and the interface toggles are not config set keys — set the theme with /theme in the TUI (it is saved for you), or edit the file directly.

wombat config set show_thinking on
wombat config set trim_reasoning on
wombat config set reasoning high

{
  "theme": "tokyo",
  "mouse": false,
  "panel": true,
  "paint_background": true
}

Themes, keys and the rest of the interface are in the CLI reference.

Environment variables

variable	effect
`WOMBAT_HOME`	Move the whole `~/.wombat` directory.
`WOMBAT_CONFIG`	Use a specific config file.
`WOMBAT_PROVIDER`, `WOMBAT_MODEL`	Override the selected provider or model.
`WOMBAT_CLASSIC`	Force the classic interface.
`EXA_API_KEY`, `TAVILY_API_KEY`, `BRAVE_API_KEY`, `SERPER_API_KEY`	Use your own search accounts; keyless backends still work.
`WOMBAT_LSP`, `WOMBAT_LSP_<EXT>`	Point the semantic capability at a language server.
`WOMBAT_TMP`	Keep temporary files out of the project.
`WOMBAT_IMAGE_`, `WOMBAT_EMBED_`	Image and embedding provider credentials.