GitHub
the banner, drawn in 88 columns

Wombat documentation

Docs, and the servers worth wiring into it.

Install, configure, gate permissions, run a fleet, attach MCP servers and skills. Everything below is the current main.

curl -fsSL https://raw.githubusercontent.com/ramsterr/Wombat/main/install.sh | bash
release
v0.2.6
build
Go 1.26.3+
license
MIT
runtime
none

Start

Wombat ships as one binary. Install from main: tagged releases can sit behind the branch, and the branch is where the features in these docs actually live.

# current main — recommended
go install github.com/ramsterr/Wombat/cmd/wombat@main
wombat setup

# or build the branch from a checkout
git clone --depth 1 --single-branch --no-tags https://github.com/ramsterr/Wombat.git
cd Wombat
go build -o wombat ./cmd/wombat

# latest tagged release — can lag behind main
curl -fsSL https://raw.githubusercontent.com/ramsterr/Wombat/main/install.sh | bash

The first two need Go 1.26.3+ and nothing else. Homebrew (brew install ramsterr/wombat/wombat) installs the tagged release too.

First run

wombat setup    # provider, key, model
wombat doctor   # config, permissions, connectivity
wombat          # chat UI

setup runs automatically on first launch and saves the provider, model and key to ~/.wombat/config.json.

Without the UI

wombat run "summarize this repository and find the test command"
wombat run --yolo "fix the failing tests and explain the change"
Windows. Install WSL2 with wsl --install, then run the macOS/Linux command inside Ubuntu. Git Bash works for the native build, but the bash tool needs a POSIX sh.
Upgrades. wombat upgrade installs the latest tagged release, which moves a main build back to the last tag. To stay on the branch, rerun the go install ...@main line.

Configure

Everything lives in ~/.wombat/config.json. wombat config prints it with keys redacted; wombat config set changes one value at a time.

wombat config
wombat config set provider openai
wombat config set model gpt-5
wombat config set fallback_models gpt-5-mini
wombat config set scout_model gpt-5-mini

Providers

  • OpenAI-compatible APIs, including self-hosted gateways
  • Anthropic
  • OpenCode
  • Local model servers

Keys can also come from the environment — OPENAI_API_KEY, ANTHROPIC_API_KEY and so on — which keeps them out of the config file.

Settings that change behaviour

wombat config set worker_full_access false
wombat config set review_writers false
wombat config set check_policy auto      # auto | worktree | merge | both
wombat config set review_policy always   # always | auto | never
wombat config set max_parallel_scouts 5
wombat config set max_parallel_writers 3

Permissions

Permissions are gated per class, not per tool. Each gate can be allow, ask or deny, and MCP can be gated per server.

  • bash
  • writes and edits
  • network
  • sensitive reads
  • mcp, falling back to mcp:<server>
wombat config set permissions.bash ask
wombat config set permissions.mcp allow
wombat config set permissions.mcp:github ask
--yolo auto-approves tool permissions for one run. Use it for trusted, non-interactive jobs, never for a repository you have not read.

Sessions and checkpoints

Sessions are stored as JSONL transcripts and scoped to a directory. Checkpoints are shadow-git snapshots, so a bad edit is one command away from gone.

wombat sessions
wombat resume last
wombat run -c "keep going"
wombat checkpoint list
wombat checkpoint restore <id>

MCP servers

Wombat is an MCP client for local stdio servers and remote Streamable HTTP/SSE servers. Their tools appear to the agent as mcp__<server>__<tool>, and each server can hold its own permission gate.

wombat mcp add playwright -- npx -y @playwright/mcp@latest
wombat mcp add context7 --url https://mcp.context7.com/mcp
wombat mcp test playwright
wombat mcp list

OAuth servers

wombat mcp add notion --url https://mcp.notion.com/mcp
wombat mcp login notion
wombat mcp test notion

Login opens a browser, completes a loopback callback with PKCE and state checks, and stores tokens in ~/.wombat/mcp-auth/ with 0600 permissions. They refresh automatically.

In the config file

{
  "mcp_servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "class": "read"
    },
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": { "Authorization": "Bearer ${CONTEXT7_API_KEY}" }
    }
  }
}

${VAR}, ${VAR:-default} and {env:VAR} expand when the server starts, so secrets stay in the environment. --class read lets delegated scouts use a read-only server; everything else stays lead-only unless you pass --workers.

Local servers run as you, with your environment. Only add servers you trust, and gate them at ask until you have watched them work.

Example servers

These are examples, not a required set — pick by the work in front of you. The MCP catalog sorts more of them by genre: code, design, art, docs, data and ops.

Add two or three, not seven. Every server puts its tool schemas in front of the model, and past that the choice of tool starts getting worse.

Playwright

browser

Accessibility-tree browser automation: click, type, assert, screenshot. The default pick for checking a UI without a second agent.

wombat mcp add playwright -- npx -y @playwright/mcp@latest

Chrome DevTools

performance

Traces, network waterfall, console and Lighthouse against a live Chrome. Use it for why a page is slow, not for clicking around.

wombat mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest

GitHub

repo

Issues, pull requests and code search without leaving the session. Pair it with a read-only class for delegated scouts.

wombat mcp add github --env GITHUB_TOKEN=<token> -- npx -y @modelcontextprotocol/server-github

Context7

docs

Version-accurate library documentation, so the model stops reciting the API from two years ago.

wombat mcp add context7 --url https://mcp.context7.com/mcp

Figma

design

Frames, variables and Code Connect mappings as structured context. Run wombat mcp login figma once, then wombat mcp test figma.

wombat mcp add figma --url https://mcp.figma.com/mcp

shadcn

components

Browse and install from any shadcn registry, including private registries declared in components.json.

wombat mcp add shadcn -- npx shadcn@latest mcp

Storybook

design system

Your real components, stories and test results, served by a running Storybook with @storybook/addon-mcp. Better than Figma once you have a library.

wombat mcp add storybook --url http://localhost:6006/mcp

Skills

A skill is a folder with a SKILL.md and optional scripts. The agent reads the description at startup and loads the body only when the task matches, so a library of skills costs almost nothing until one is used. Install them with the skills CLI; they land in ~/.agents/skills and symlink into each agent that supports them.

npx skills add anthropics/skills -g -s frontend-design
npx skills add vercel-labs/agent-skills -g -s web-design-guidelines
npx skills ls -g

Drop -g to install into a project's .agents/skills instead of your user directory. Skills run with the same permissions as the agent, so read one before you install it.

Skills vs MCP. A skill is instruction and taste. An MCP server is reach. Install skills to change how the agent decides, MCP servers to change what it can touch.

frontend-design

taste anthropics/skills

Forces a design direction, a type scale and a token system before any code, and names the templated looks to avoid. The single biggest jump for greenfield UI.

npx skills add anthropics/skills -g -s frontend-design

web-design-guidelines

review vercel-labs/agent-skills

Audits existing UI against the Web Interface Guidelines and returns terse file:line findings. Bad at generating, good at catching.

npx skills add vercel-labs/agent-skills -g -s web-design-guidelines

webapp-testing

verify anthropics/skills

Playwright scripts plus a server helper, so an agent can verify a local app without an MCP server. Needs Python Playwright and Chromium.

npx skills add anthropics/skills -g -s webapp-testing

theme-factory

palette anthropics/skills

Ten palettes with matched font pairings for decks, docs and landing pages, plus a showcase PDF.

npx skills add anthropics/skills -g -s theme-factory

vercel-react-best-practices

react vercel-labs/agent-skills

Performance rules for React and Next.js: data fetching, bundle size, rendering boundaries.

npx skills add vercel-labs/agent-skills -g -s vercel-react-best-practices

vercel-react-view-transitions

motion vercel-labs/agent-skills

Page, route and shared-element motion with the View Transition API, without a third-party animation library.

npx skills add vercel-labs/agent-skills -g -s vercel-react-view-transitions

Commands

commandwhat it does
wombatopen the chat UI
wombat run "<task>"run one task and exit
wombat run -c "<task>"continue the latest session
wombat resume [id|last]reopen a session
wombat sessionslist sessions for this directory
wombat setupchange provider, key or model
wombat models [provider]list available models
wombat doctordiagnose config and connectivity
wombat configshow config, with keys redacted
wombat config set <key> <value>change one setting
wombat mcp add|list|testadd and check MCP servers
wombat mcp login|logoutsign in to an OAuth MCP server
wombat checkpoint listlist shadow-git checkpoints
wombat checkpoint restore <id>restore a checkpoint
wombat upgradeinstall the latest stable release
wombat versionprint the version

Inside the chat, slash commands cover the rest: /model, /configure, /theme, /sources, /preview, /cost, /compact, /copy.

Keys

  • / command palette
  • @ file picker with tab completion
  • ctrlo open the newest preview
  • ctrlb toggle the inspector
  • ctrlt cycle themes
  • ctrlr add a project reference
  • ctrly copy the last reply
  • ctrlp previous prompt
  • alt1–5 jump between panels
  • esc stop the current run
  • ? full key map
  • ctrlc quit

Themes

Fifteen palettes ship in the binary. In the app, /theme opens the picker, ctrl+t cycles, and the terminal background is tinted while Wombat runs and restored on exit.

wombat v0.2.6

modelclaude-sonnet-4.5

thememonokai

context 38%

previewlocalhost:5173 · ready

fix the failing tests

monokai

Troubleshooting

wombat: command not found
Add ~/.local/bin to PATH, or run the binary by its full path. go install writes to $(go env GOPATH)/bin.
No provider or model
Run wombat setup, then wombat doctor. Both are safe to re-run.
Writers fail with “main workspace has tracked changes”
Workers use git worktrees and need a clean tracked tree. Commit or stash first.
Connection reset by peer
Wombat retries transient errors with backoff, including mid-stream, and asks the model to continue when provider retries run out. If it still fails, check your network, proxy or VPN.
An upgrade replaced my source build
wombat upgrade installs the latest tagged release. Rebuild from source to stay on main.