Mullet
Provides a Docker tool for executing and managing Docker containers, enabling containerized code execution and testing.
Provides a Git tool for version control operations, including diffs, staged changes, and repository interactions.
Checks the public GitHub repository for the latest version via the auto-update checker, keeping the server up to date.
Integrates with Google Gemini models (Gemini 2.5, Gemini Flash) as a provider, supporting optional Gemini CLI subscriptions and API access.
Integrates with Ollama as a local LLM provider, enabling self-hosted model inference for cost-effective task routing.
Integrates with OpenAI models (GPT-5) and exposes an OpenAI-compatible REST + WebSocket API for chat completions and model listing.
Exposes Prometheus metrics at /metrics for monitoring request counts, token usage, latency, and tool-call activity.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Mullet refactor the auth module and route it to the cheapest capable model"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Mullet
Mullet runs a large coding job in your repo unattended: you approve a task tree, then each step runs in a sandboxed private clone with no network, and provider keys stay outside the sandbox.
A step counts only when Mullet's own gates pass, never on a model's word. You get back a branch and an evidence report, and your checkout is untouched until you merge.
A ladder tries free and local workers before paid ones, under the daily and weekly spending limits you set.
Install and first job: Install and Quick start. Design decisions: docs/adr/.
Each step is done by a worker in a sandboxed private clone. A step passes only when Mullet's own gates pass: real changes in the diff, files within scope, no secrets, a clean build, tests no worse than before, and a fresh review. Nothing is marked done because a model said so.
Mullet also serves Trawl, a knowledge search for your own documents and code, over MCP.
Status
Mullet is maintained. Jobs run on Linux. On macOS they refuse to start for now, because there is no sandbox there yet; the rest of Mullet works. The code, model list and prices date from October 2026.
Related MCP server: Vibecoders MCP
Install
Mullet isn't on PyPI (the name there belongs to another package), so install it from GitHub. It needs Python 3.10 to 3.12, git, and uv or pipx. Jobs also need the claude command-line tool, logged in, and on Linux, bubblewrap and socat.
curl -fsSL https://raw.githubusercontent.com/tomgould/mullet-public/main/scripts/install.sh | bashThat runs uv tool install git+https://github.com/tomgould/mullet-public.git (or the pipx equivalent). Run it again to update. Add --version X.Y.Z or --ref <branch|tag|sha> to pin a release or ref, and --dry-run to print the command without running it (with curl: ... | bash -s -- --version X.Y.Z). Optional extras are gemini, bedrock, postgres, gpu and all. To work on Mullet itself, clone it and run pip install -e ".[dev]" in a virtualenv.
Quick start
mullet doctor # checks Claude Code, the sandbox and your setup
cd your-repo
mullet job plan "add retry with backoff to the HTTP client" # a read-only session proposes a task tree
mullet job approve <id> # you approve the plan
mullet job run <id> # runs in the background; status, tail, stop, resume
mullet job report <id> # evidence for each step
mullet job merge <id> # copies the branch into your repo; never pushesmullet job show <id> prints the plan. Add --yaml to get an editable plan file, and pass it back with --plan-file. --single skips the planner and makes one step. mullet job list shows recent jobs, and mullet job discard <id> removes one. A job with steps that could only be partly checked (shown as unverified) is refused by merge until you review them and add --allow-unverified.
How a job works
The planner breaks the goal into a tree of steps, up to three levels deep and 40 steps, until each leaf fits one pass. Only Mullet creates steps. Workers never start workers.
You read the plan and approve it. This is the first of two approvals.
Each step runs in a private clone of the commit the job started from. A worker edits the files. Mullet then snapshots the tree, runs the gates, and commits exactly the tree it judged.
A failed step is reset and tried again with the gate output, up to three attempts. After that it is blocked. A parent step passes only when its children pass and the full checks pass on their combined change.
When the job finishes, you read the report and run
mullet job merge. This is the second approval.
One Claude worker runs at a time across all jobs, because they share one subscription's allowance; cheaper workers have slots of their own (three by default, MULLET_API_WORKERS). When Claude Code reports a usage limit, the job pauses until the reset and carries on. A pause does not count as an attempt. Stop and kill -9 are safe: mullet job resume returns the clone to the last commit Mullet recorded.
The gates
A gate that fails fails the step. A gate that could not run shows as unverified, never as passed.
Gate | What it checks |
G0 | The repo's checks on the starting commit, once per job, so later results have a baseline |
G1 | The diff from git shows a real change |
G2 | Files stay in scope; protected paths such as |
G3 | Added lines hold no secrets and no risky patterns |
G4 | Lint, type check and build |
G5 | Tests, compared with G0: new failures, and tests that passed before and are skipped now, count against the step |
G6 | No removed assertions or newly skipped tests, unless the step is allowed to |
G7 | A fresh read-only Claude session reviews the diff, without seeing the worker's transcript. It can block a step, never pass one |
Job state is kept in a SQLite ledger, and a step's status comes from gate results only. The report is built from the ledger. Anything the worker says about itself is labelled as a claim.
Safety
Workers run inside bubblewrap on Linux: read-only root, your home directory hidden, no network, and an allowlisted environment so none of Mullet's loaded keys get through. Gate commands run in the same sandbox. If the sandbox can't start, the job refuses to run. There is no unsandboxed fallback.
The private clone keeps its git directory out of the worker's reach, so a worker can't move refs or rewrite history. Mullet runs its own git commands with hooks off.
Credentials: the Claude Code worker is your own installed
claude -p, using your own login. Mullet never reads, stores or passes Claude's credentials.ANTHROPIC_API_KEYis left out of the worker's environment, because inclaude -pit silently replaces your login and bills per token. Plan a job with--billing apito opt in.mullet doctorwarns when the key is set. Check Anthropic's current terms for your own use.mullet job mergefetches the job branch into your repo as a new branch and stops. It refuses an existing branch name. It never pushes.
Workers
A step's worker is Claude Code, your own claude -p, or opencode on a model you name: Kimi on Moonshot's API, an OpenRouter model, an OpenRouter :free model, or a model in LM Studio on your own machine. opencode is off unless a repo's stored profile lists it in allowed_executors. Every worker runs in the same sandbox and faces the same gates, and reaches its provider through a key proxy on a Unix socket, so the sandbox never sees an API key and each attempt may only use its own model.
The delegation ladder
With a ladder: section in ~/.config/mullet/config.yaml, each step goes up a ladder of workers, one attempt per rung, cheapest first unless Claude's week has room:
ladder:
kimi: moonshotai/kimi-k2.7-code # Moonshot's own API (MOONSHOT_API_KEY)
openrouter: [openrouter/z-ai/glm-5.3] # paid OpenRouter models, in order
free: openrouter/<model>:free # optional; verified-public GitHub repos only
local: lmstudio/qwen3.6-35b-a3b # optional; LM Studio on 127.0.0.1:1234
local_by_day: false # local only in night mode
max_spend: 4.0 # dollars per job on the paid rungs
routing: # optional OpenRouter host choice per model
openrouter/z-ai/glm-5.3: {only: [z-ai]}The planner marks each step mechanical, design, analysis or integration; mechanical and checkable design steps start low, the rest start with Claude or Kimi. Planning and review always stay on Claude.
The order follows Claude's paced weekly usage, read from what Claude Code reports: with room, Claude comes before the paid rungs; when the week is tight, Claude is the last resort.
Free models only see repos GitHub confirms are public. Paid OpenRouter requests always ask for hosts that don't keep prompts, and by default skip hosts serving a 4-bit copy of the model.
Each job has a spending cap on the paid rungs. A provider error moves a step up without using an attempt, and a model that failed a step's gates isn't tried again elsewhere.
mullet ladder reportadds up every job's attempts by rung, step kind and model from the ledger, with a short list of what to change.mullet job laddershows which rungs work now;mullet job retry <job> <step> --rung claudegives a blocked step another go. The report shows each attempt's rung, model and cost.
Local models and night mode
mullet night on [--until HH:MM]lets overnight jobs lean on the local GPU: local attempts get longer and wait for room on the machine. It ends at its time or when you come back.mullet local status|restart|check --fixkeeps LM Studio usable, andmullet local watchdog --installchecks it every two minutes and restarts it when it is stuck.mullet strategy set --budget USD --delegation ladder|claude-only|offrecords this session's budget and delegation choice;mullet job planfollows it while it is fresh.mullet reapstops idle or orphaned Mullet work (test workers, stray opencode runs, idle local models, stale temp directories);--dry-runshows what it would do.A machine guard (one GPU lease across Mullet's processes, plus VRAM, RAM and temperature limits) keeps jobs, local models and reindexing from fighting over the card.
Not built: a macOS sandbox, so jobs cannot run there yet.
Spending limits and other settings
Spending is unlimited until you set limits in ~/.config/mullet/config.yaml. ladder.max_spend caps one job; budget.envelope and budget.per_rung cap all jobs together per UTC day or week:
budget:
envelope: {daily: 25.0, weekly: 100.0}
per_rung:
kimi: {daily: 15.0}
openrouter: {weekly: 40.0}
warn_below_usd: 5.0 # doctor and notifications flag provider credit under thisCost comes from what the provider's responses say. Each attempt gets an allowance, and the key proxy refuses requests with HTTP 402 once it is spent. mullet job report ends with a provider check that sets the ledger's spend beside each provider's own figure. docs/CONFIGURATION.md covers these, which toolsets and files a delegated model may touch (delegation.toolsets, delegation.file_deny), and how mullet serve guards itself (Host and Origin checks, a token in serve-token). mullet config show lists every active setting and where it came from.
Notifications
Mullet tells you when a job blocks, pauses or finishes. Desktop notifications are on by default. A Slack incoming webhook is sent only in working hours. Each message ends with your paid providers' credit and Claude's weekly use, when Mullet can read them.
Variable | Meaning |
| Channels: |
| The Slack incoming webhook URL |
| Working hours for Slack, default |
| Time zone for those hours, default the machine's local time zone |
Where files live
mullet paths prints every directory. Settings and keys go in ~/.config/mullet/.env ($MULLET_CONFIG_DIR if set). State, data and caches follow the XDG directories. An older ~/.mullet still works, and mullet migrate-state --dry-run shows what moving it would do. Your stored job profile for each repo is in the projects folder of the config directory. A repo can add .mullet/project.yaml, which can only tighten it.
mullet setup-claude registers the MCP server and Mullet's skills with Claude Code for every project. Run it with --dry-run first, and --uninstall removes exactly what it added. It never edits CLAUDE.md. session-strategy is added by default (--hooks none skips it); the other hooks are opt-in: --hooks list describes them, and mullet hook <name> runs one. --hooks session-strategy opens each session with one question about budget and delegation, which mullet strategy set records and mullet job plan follows.
Trawl and MCP
Trawl indexes collections of documents and code, called pools. It searches them by keyword and by meaning together, re-ranks the results and can build a knowledge graph. mullet mcp serves it to Claude Code and other MCP clients, with mullet search, mullet pool, mullet reindex and mullet graph on the command line. docs/REINDEX.md covers pools and crawling websites.
The MCP server still has the older delegation tools, which send a task to another model provider. They are off by default; MULLET_DELEGATION=on in ~/.config/mullet/.env switches them on. Trawl, status and budget keep working. Presets such as local-only limit which providers they may use:
Preset | Providers | opencode model |
| all |
|
|
|
|
|
| none |
|
|
|
The old orchestration modes (ultrawork, ralph, autopilot, team, eco) and the overnight loop are gone.
Documentation
The guides are in docs/:
mullet --help lists every command. GitHub Actions runs the tests on Linux and macOS; see CONTRIBUTING.md to work on Mullet.
Licence
Mullet is source-available under the Business Source License 1.1. You may copy, change and redistribute it, and use it outside production. You may also use it in production, free, for any purpose: on your own, inside a company or team, on any number of machines, to build software you sell or ship. The one thing the licence does not cover is offering Mullet, or a service whose value comes substantially from it, to other people as a hosted, managed or embedded service (an API or SaaS that runs Mullet's job runner or search for them). That 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.
Available Tools
53 toolsmullet_analyzeA
Analyze a task's complexity and show what provider/tier the router would select. Useful for understanding routing decisions.
Inputs: task (required), agent_type.
mullet_budgetB
Query current token spend and budget limits.
Inputs: no named parameters.
mullet_delegateA
Delegate a subtask to a Mullet child agent. The child runs independently with its own context and tools, routed by complexity.
Inputs: goal (required), client, context, providers.
mullet_opencodeA
PREFERRED for code editing tasks. Runs the task as a single gated Mullet job on the delegation ladder (the cheapest worker that can pass the project's gates does the work) and applies the result to the working tree only after the gates pass. Changes are left unstaged and are never committed or pushed. Returns JSON with status (applied, passed_not_applied, failed, blocked, unverified or timeout), job id, report path, rung, model, cost, gate summary and files changed.
Inputs: task (required), cwd, files, model, +2 more.
mullet_providersA
List available LLM providers and their health status.
Inputs: no named parameters.
mullet_rememberC
Store a memory in a project's knowledge base for future sessions.
Inputs: key (required), client (required), content (required).
mullet_runA
For code editing tasks (reading/modifying files), use mullet_opencode instead: it runs the edit as a gated Mullet job and applies the result to the working tree only after the gates pass. Use mullet_run only for: analysis, planning, research, review, or text generation tasks where no files need to be written. Routes to the optimal provider (local GPU or cloud) based on complexity.
Inputs: task (required), tier, apply, files, +5 more.
mullet_searchC
Search project knowledge for relevant context. Uses Trove's hybrid search engine.
Inputs: query (required), client (required), top_k.
mullet_statusA
Check Mullet's current status — active tasks, provider health, budget.
Inputs: no named parameters.
mullet_swarmB
Fan-out a goal across many Kimi K2 calls in parallel and synthesize the results. Use for tasks that can be split across multiple files, items, or independent sub-questions.
Inputs: goal (required), apply, files, items, +4 more.
trawl_agents_getB
Get full agent template config including system prompt.
Inputs: agent_name (required).
trawl_agents_listB
List available agent templates, optionally filtered by tag.
Inputs: tag.
trawl_build_graphB
Build or rebuild the knowledge graph for a client. Runs in background.
Inputs: pool_name (required), sample, rebuild, workers, +1 more.
trawl_connect_githubC
Add a GitHub account, org, or repo as a source for a pool.
Inputs: owner (required), pool_name (required), repo, exclude_repos, +1 more.
trawl_crawl_webC
Crawl a website and save pages as Markdown for a client.
Inputs: url (required), pool_name (required), max_pages, stay_in_path.
trawl_docs_lookupA
Look up documentation for a library using Context7 (version-aware) with fallback to local Trawl pools. Use this when you need API docs, usage examples, or version-specific information for any library.
Inputs: query (required), library (required), sources, version.
trawl_find_symbolB
Find a specific code symbol (function, class, variable) by name.
Inputs: symbol_name (required), language, pool_name, symbol_type.
trawl_get_poolC
Get information about the currently loaded pool.
Inputs: no named parameters.
trawl_graph_exportB
Export knowledge graph as D3.js-compatible JSON for visualization.
Inputs: max_nodes, pool_name.
trawl_graph_pruneA
Remove orphaned entities, relationships, and processed-chunk tracking whose source chunks no longer exist in the collection.
Inputs: pool_name (required).
trawl_graph_statsB
Get knowledge graph statistics (node/edge counts, entity types).
Inputs: pool_name (required).
trawl_ingest_fileC
Ingest a single file into a pool.s collection.
Inputs: file_path (required), pool_name (required).
trawl_ingest_statusC
Check the status of an ingestion job.
Inputs: job_id, pool_name.
trawl_ingest_urlC
Ingest content from a URL into a pool.s collection.
Inputs: url (required), pool_name (required).
trawl_list_poolsA
List all available knowledge pools. Each client has its own indexed document collection.
Inputs: no named parameters.
trawl_list_reposC
List GitHub repos indexed for a client.
Inputs: pool_name (required).
trawl_list_sourcesC
List document sources for a client.
Inputs: pool_name (required).
trawl_load_poolB
Load a specific pool for subsequent searches.
Inputs: pool_name (required).
trawl_memory_deleteB
Delete a memory by namespace and key.
Inputs: key (required), namespace, pool_name.
trawl_memory_listB
List all stored memories, optionally filtered by namespace.
Inputs: namespace, pool_name.
trawl_memory_searchC
Search stored memories semantically.
Inputs: query (required), top_k, namespace, pool_name.
trawl_memory_storeC
Store a memory/note with semantic search capability.
Inputs: key (required), content (required), ttl, metadata, +2 more.
trawl_pool_deleteA
Permanently delete a Trawl pool (directory + index). Requires confirm=true.
Inputs: pool_name (required), confirm.
trawl_prompts_findB
Find prompts by combining local index and live API search.
Inputs: query (required), type, top_k.
trawl_prompts_getB
Get a specific prompt template by ID with optional variable substitution.
Inputs: prompt_id (required), variables.
trawl_prompts_search_liveC
Search the prompts.chat API for prompt templates.
Inputs: query (required), tag, sort, type, +2 more.
trawl_recentA
List a pool's documents newest first, by the best date known for each: a page's own published date, a PDF's creation date, when the web crawler first saw it, or when its text last changed. Use this, not search, for 'what's new' / 'recent news' questions.
Inputs: pool_name (required), limit, since.
trawl_reindex_poolB
Trigger a full reindex of a client's documents. Runs in the background.
Inputs: pool_name (required).
trawl_run_agentC
Run a Trove agent with local LLM — searches context, applies agent prompt, generates response.
Inputs: query (required), agent_name (required), top_k, pool_name, +1 more.
trawl_searchB
Search across all indexed documents using hybrid BM25 + vector search.
Inputs: query (required), mode, top_k, pool_name, +2 more.
trawl_search_codeC
Search code specifically with language and symbol type filters.
Inputs: query (required), top_k, languages, pool_name, +1 more.
trawl_search_entitiesC
Search for entities in the knowledge graph.
Inputs: query (required), top_k, pool_name, entity_type.
trawl_search_multiB
Search across multiple clients with reciprocal rank fusion. Omit clients to search all.
Inputs: query (required), mode, top_k, clients, +1 more.
trawl_search_poolC
One-shot search: load a client and search in one call.
Inputs: query (required), pool_name (required), top_k.
trawl_search_relationshipsC
Search for relationships between entities in the knowledge graph.
Inputs: entity (required), max_hops, pool_name, relationship_type.
trawl_search_repoC
Search within a specific repository.
Inputs: query (required), repo_name (required), top_k, pool_name, +1 more.
trawl_summarizeC
Search and return concise summaries of results using LLM.
Inputs: query (required), top_k, pool_name, providers.
trawl_sync_poolB
Incremental reindex — only process new/modified files since last index. Fast.
Inputs: pool_name (required).
trawl_sync_sourcesC
Sync all sources for a client (pull latest from git repos, etc.).
Inputs: pool_name (required).
trawl_workflow_createC
Create a workflow with named steps and dependency ordering.
Inputs: name (required), steps (required), pool_name.
trawl_workflow_listB
List all workflows, optionally filtered by status.
Inputs: status, pool_name.
trawl_workflow_statusB
Get workflow status and step progress.
Inputs: workflow_id (required), pool_name.
trawl_workflow_updateC
Update a workflow step's status.
Inputs: status (required), step_id (required), workflow_id (required), result, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 53 tools
Several tools have overlapping search and memory purposes: mullet_search, trawl_search, trawl_search_pool, trawl_search_multi, trawl_summarize, mullet_remember, and trawl_memory_* all compete for similar retrieval/storage intents. Execution tools also blur together: mullet_run, mullet_opencode, mullet_delegate, mullet_swarm, and trawl_run_agent all perform routed LLM work with subtle boundary distinctions that an agent must parse carefully.
The mullet_ and trawl_ prefixes provide a useful top-level grouping, and all names are snake_case. However, within trawl the convention is mixed: some tools use action_resource order (trawl_search_entities, trawl_get_pool, trawl_load_pool) while others use resource_action order (trawl_agents_list, trawl_pool_delete, trawl_memory_store, trawl_workflow_create).
At 53 tools, the surface is very large and heavy for a single server, spanning orchestration, search, ingestion, graph operations, memory, workflows, agents, prompts, and docs. While these are related platform capabilities, the count far exceeds a well-scoped set and increases selection burden.
The surface covers many lifecycle operations, including memory store/search/list/delete, workflow create/list/status/update, pool management, ingestion, graph build/stats/export, agents, prompts, and docs lookup. But there are notable gaps such as no clear entity or relationship update/delete beyond graph pruning, no task cancellation or explicit active-task listing, and limited update/delete coverage for prompts and agents.
Maintenance
Related MCP Connectors
LLM cost optimization gateway, repo token-waste auditor & model arbitrage MCP server.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Chat, image, video, and audio models from many vendors behind one remote MCP server and one key.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceLocal MCP server that exposes fixed tools for GPT, Claude, and Gemini while routing to any OpenAI-compatible chat completions backend with independent configuration per target.1-
- AlicenseAqualityDmaintenanceOne MCP that turns Claude Code into your whole dev stack by swallowing other MCP servers, delegating to Codex & Gemini on your CLI subscriptions, remembering projects in a searchable knowledge graph, and carrying setup across sessions — secret-free by design.234MIT
- FlicenseNot gradedqualityAmaintenanceExposes an MCP server that pools free LLM provider routes behind one OpenAI-compatible endpoint, enabling chat and coding-agent requests with automatic failover, model/route discovery, and keyless start when available. It can begin serving without credentials whenever an enabled keyless route is up.-
- FlicenseNot gradedqualityAmaintenancePublishes an MCP server that pools many free LLM providers — including keyless routes — behind one local OpenAI-compatible endpoint, letting coding agents and compatible clients discover, route to, and fail over across available chat models. It also exposes tools for status, model inventory, and capacity/health inspection.-