Skip to main content
Glama

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 | bash

That 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 pushes

mullet 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

  1. 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.

  2. You read the plan and approve it. This is the first of two approvals.

  3. 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.

  4. 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.

  5. 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 .git*, CLAUDE.md, CI workflows and lockfiles are untouched

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_KEY is left out of the worker's environment, because in claude -p it silently replaces your login and bills per token. Plan a job with --billing api to opt in. mullet doctor warns when the key is set. Check Anthropic's current terms for your own use.

  • mullet job merge fetches 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 report adds up every job's attempts by rung, step kind and model from the ledger, with a short list of what to change.

  • mullet job ladder shows which rungs work now; mullet job retry <job> <step> --rung claude gives 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 --fix keeps LM Studio usable, and mullet local watchdog --install checks it every two minutes and restarts it when it is stuck.

  • mullet strategy set --budget USD --delegation ladder|claude-only|off records this session's budget and delegation choice; mullet job plan follows it while it is fresh.

  • mullet reap stops idle or orphaned Mullet work (test workers, stray opencode runs, idle local models, stale temp directories); --dry-run shows 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 this

Cost 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

MULLET_NOTIFY

Channels: desktop, slack, both separated by a comma, or off

MULLET_SLACK_WEBHOOK

The Slack incoming webhook URL

MULLET_NOTIFY_HOURS

Working hours for Slack, default Mon-Fri 09:00-17:30

MULLET_NOTIFY_TZ

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

balanced-mix (default)

all

moonshot/kimi-k2.6

local-only

local

lmstudio/ornith-1.5-35b-a3b

claude-only

sonnet, haiku, opus-4-8, used by Claude Code itself, never delegated

none

cheap-cloud

kimi, gemini

moonshot/kimi-k2.6

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 tools
mullet_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_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_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_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

    C2.8/5.0

    Scored across 53 tools

    Disambiguation2/5

    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.

    Naming Consistency3/5

    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).

    Tool Count2/5

    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.

    Completeness3/5

    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

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      One 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.
      23
      4
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Exposes 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Publishes 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.
      -