Troubleshooting

Before anything else

wombat doctor
wombat config
wombat version

Install and startup

wombat: command not found

go install writes to $(go env GOPATH)/bin; the installer uses ~/.local/bin. Add the right directory to PATH, or run the binary by full path.

No provider or model

Run wombat setup, then wombat doctor. Both are safe to re-run and keep your other settings.

The new UI does not appear

It is opt-in: cd tui && npm install && npm run build, then run Wombat from that checkout. Node 26.4+ is required. Without the build you get the classic TUI, which has every feature except the rendering.

Connection reset by peer

Wombat retries transient errors with backoff, including mid-stream: it clears the partial output, retries, and asks the model to continue when the provider's retries run out. If it still fails, check the network, proxy or VPN.

HTTP 429 or a rate limit

Set a fallback model (wombat config set fallback_models ...) or a cheaper model for workers (scout_model). Benchmark runs hit this too; the comparison page names the model each suite used.

Agent behaviour

Writers fail with "main workspace has tracked changes"

Workers use git worktrees and need a clean tracked tree. Commit or stash first. keep_worktrees keeps the worktrees around if you want to inspect a failed merge.

A headless run stops or hangs on a question

It should not: wombat run never asks. Vague prompts state assumptions and exit 0, and the question tool is capped at two calls per session. If a run is waiting on a permission instead, that is a permission gate — use --yolo for a trusted job or set the class to allow.

A search was refused

The bash tool rejects find, grep, rg, fd, ls, du, tree, mdfind and locate against /, ~, $HOME, a parent directory, or anything outside the workspace. Use glob and grep, or scope the command to the project. This guard removed the 229s find / that used to dominate a run.

Tokens are higher than expected

Check /toolset and /cost. The default auto profile adds capabilities when the prompt implies them; minimal or coding keeps the nine-tool registry. Orchestration tools are attached when the orchestrator is on — orchestrator: false is the lean path.

A custom agent never runs

Check wombat agent list to see which definition Wombat resolves, then select it with /agents or --agents. A readonly agent cannot write, chat mode forces every agent read-only, and a definition with permissions: { "write": "deny" } will never produce a patch.

Skills do not show up

Skills are markdown files in ~/.wombat/skills/<name>.md or .wombat/skills/<name>.md. The project copy wins on a name clash. /skill lists what Wombat found; a skill is only used when an agent names it.

MCP and previews

An MCP server will not start

wombat mcp test <name> connects, lists tools and prints the server's stderr. The startup timeout is 15s — use --timeout 60 for a slow first npx download. Remote endpoints must be HTTPS unless they are loopback.

MCP tools are missing for workers

Servers are lead-only unless added with --workers. A server added with --class read is available to scouts without giving them write access.

No preview bar appears

The bar only appears after a tool reports a local URL such as http://localhost:5173. /previews lists everything collected so far, and ctrl+o opens the newest.

An upgrade replaced my source build

wombat upgrade installs the latest tag. Rebuild with go install github.com/ramsterr/Wombat/cmd/wombat@main to move back to the branch.

Reset

mv ~/.wombat/config.json ~/.wombat/config.json.bak
wombat setup

# remove everything, including sessions and MCP logins
rm -rf ~/.wombat

Move the directory rather than deleting it if you might want the sessions back: the transcripts are plain JSONL and readable without Wombat.