Mullet

Mullet takes work off an AI coding tool such as Claude Code. Over the Model Context Protocol (MCP), it sends each task to the cheapest model that can handle it, from a local model in LM Studio or Ollama to Kimi, OpenRouter, Gemini or Claude, and it searches your own documents and code.

Status

Mullet is paused, not finished. I still run its knowledge search, Trawl, but I've turned delegation off: a larger Anthropic subscription turned out quicker than handing work to other models. If Anthropic's prices rise, I'll switch it back on and send most of the work to cheaper models through Kimi and OpenRouter. Set MULLET_DELEGATION=off in .env to turn delegation off; Trawl, status and budget keep working. The code, model list and prices date from October 2026.

Related MCP server: OpenAI-Compatible MCP Gateway

Install

Mullet isn't on PyPI (the name there belongs to another package), so install it from a clone. It needs Python 3.10 or later.

git clone https://github.com/tomgould/mullet-public.git
cd mullet-public
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

Keep the install editable (-e): the Claude Code hooks run from scripts/hooks/ in the clone. Optional extras are gemini, bedrock, postgres, gpu, all and dev, for example pip install -e ".[gemini]". opencode needs Node.js 18 or later.

Quick start

cp .env.example .env     # add the API keys you have
mullet doctor            # checks the install and which providers it can reach
mullet explain "add a retry with exponential backoff to the HTTP client"   # scores a task, calls no model
mullet "explain this codebase in one paragraph"                            # runs a task

Mullet reads .env from the root of the clone. KIMI_API_KEY alone is enough to start, and a local model in LM Studio or Ollama needs no key. ANTHROPIC_API_KEY is optional: without it, Mullet hands Anthropic work back to Claude Code or uses the claude command-line tool.

The MCP server is mullet mcp. To add it to Claude Code for every project:

claude mcp add --scope user mullet -- mullet mcp

mullet setup-claude goes further. Read what it does first, or run it with --dry-run: it installs hooks that run in every project, adds delegation rules to ~/.claude/CLAUDE.md, installs skills, agents and a status line into ~/.claude/, and installs opencode with npm.

Documentation

The guides are in docs/:

• Quick start

• Installation, with guides for Linux, macOS and ChromeOS

• Architecture

• Model routing

• opencode integration

• API reference

• Writing skills

• Reindexing knowledge pools

• Changelog

The rest of this page is a reference.

What it does

• Scores each task out of 100 before it picks a model, from keywords, the number of subtasks, how much of the system it touches and whether it needs tests. The score puts the task in a tier: LOW, STANDARD, ADVANCED or CRITICAL. mullet explain shows the working without calling a model.

• Watches the budget. It reads how much of a Claude subscription's five-hour and weekly allowance has gone and, as that runs low, moves work away from Claude to providers such as OpenRouter and Kimi.

• Edits files through opencode, an open-source coding agent, then checks what it did. The list of changed files comes from git status, not from the model's report, and a classifier with no model behind it flags edits that often mean trouble.

• Splits a goal across parallel Kimi calls and merges the answers, and has longer-running modes that break a task up, work through it and check the result.

• Searches your own documents and code with Trawl, its knowledge engine. Trawl indexes collections called pools, searches them by keyword and by meaning together, re-ranks the results and can build a knowledge graph.

• Limits which providers it may use through presets.

• Serves an OpenAI-compatible API with mullet serve.

Using it from Claude Code

The MCP server has 10 Mullet tools and 43 Trawl tools.

The Trawl tools manage pools, search code, documents and the knowledge graph, and list a pool's newest documents. With MULLET_DELEGATION=off, mullet_run, mullet_opencode, mullet_swarm and mullet_delegate refuse, and the rest keep working.

Routing

Routing has three stages.

1. A preflight step estimates how much the task will read and write and how hard it is. It asks a local model first, then Gemini Flash, and falls back to heuristics.

2. A routing matrix picks the cheapest model that can take that input and output at that complexity. Size estimates get a 10% margin before they're compared with a model's context window.

3. A fallback chain takes over if that model isn't available.

Local models are classified from their names, by size and by whether they're built for code, vision or reasoning, so routing works with whatever is loaded in LM Studio. A fifth tier, PREMIUM, is for the orchestrating model only: mullet override on sends work to Opus until the current five-hour window resets.

mullet models and mullet cost list the models and prices Mullet knows about. docs/MODEL_ROUTING.md has the detail.

Budget guard

mullet.hud.guard.check_budget() returns one of three states. It's "go" normally. It's "throttle", which steers work to a cheaper provider, once five-hour usage reaches 70% (55% when weekly usage is 85% or more) or the day's share of the weekly allowance drops below 8%. It's "pause" when five-hour usage is at least 95% and weekly usage at least 90%.

Provider presets

A preset limits which providers Mullet may use.

mullet preset list          # * marks the active one
mullet preset use cheap-cloud
mullet preset show local-only
mullet preset add --name my-preset --label "My preset" --providers local,kimi --speed balanced
mullet preset remove my-preset

Orchestration modes

Over MCP, mullet_run takes standard, ultrawork or ralph as its mode.

Built-in tools

A task run by Mullet's own agent can use 24 tools, in mullet/core/tools/:

Tools from other MCP servers can be added through the client in mullet/core/tools/mcp_client.py.

Commands

mullet --help lists the rest.

API server

mullet serve offers /v1/chat/completions, /v1/models, /health, /metrics (Prometheus) and a WebSocket at /ws.

mullet serve
curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"hello"}]}'

docs/API.md covers the REST, WebSocket and admin endpoints.

Configuration

• API keys and switches such as MULLET_DELEGATION go in .env; .env.example lists them.

• Project settings go in mullet.yaml in the project, or ~/.mullet/config.yaml; mullet.yaml.example shows the shape. For example, to add an OpenAI-compatible server on a port Mullet doesn't probe:

  providers:
    my_server:
      type: openai_compatible
      base_url: http://localhost:8080/v1
      models:
        default: my-model

• Knowledge pools live in ~/.mullet/pools/, or wherever TRAWL_POOLS_DIR points.

• A pool can also crawl a website on every mullet reindex, from its sitemap, with linked PDFs and Office files. docs/REINDEX.md has the options.

Development

pip install -e ".[dev]"
pytest

There are more than 17,800 tests. GitHub Actions runs them on Python 3.10, 3.11 and 3.12, and ruff checks for errors. See CONTRIBUTING.md.

Licence

Mullet is source-available under the Business Source License 1.1. You may copy, change and redistribute it, and use it outside production. One developer may also use it in production, free, for their own work on one running instance, but not offer it, or a service based on it, to anyone else. Any other production use needs a commercial licence; LICENSE says how to ask.

Each version becomes available under the Apache License 2.0 on 3 April 2030, or four years after its first public release if that comes sooner.