WorkerMill

Free local models write the code. Smart models plan and review. You pay pennies instead of dollars.

Most AI coding tools run every token through an expensive cloud model. WorkerMill flips that. A team of specialist AI personas — each routable to a different provider — handles the heavy lifting on local models or affordable cloud APIs. You only burn premium tokens on planning and review. Same quality, fraction of the cost.

Point it at a ticket. Get a pull request — planned, built by experts, and independently reviewed.

Quick Start · How It Works · Commands · Providers · Docs

Quick Start

npx workermill

No API key required — select Ollama during setup to run fully local. Or bring your own keys for Anthropic, OpenAI, Google, xAI, or any OpenAI-compatible provider. Setup takes 60 seconds.

# Or install globally
npm install -g workermill

# Check your setup
wm doctor

No server, no Docker, no account. First run walks you through provider setup — pick a model, add a key (or point at Ollama), and you're building.

Requirements: Node.js 20+, Git, and an LLM provider (Ollama for local, or an API key). GitHub CLI (gh) is optional but needed for automatic PR creation.

What It Does

Point at a ticket. Get a pull request.

Point WorkerMill at your GitHub Issues, Jira, or Linear tickets. It plans the work, assigns specialist AI personas — backend, frontend, devops, security — writes the code, runs your tests, reviews with a separate model, and opens a PR.

> /build #42

 coordinator  Fetched #42: Add product export to CSV

 planner  Reading codebase... 38 files analyzed
 planner  2 stories:
          [backend_developer] CSV export endpoint with filters, auth, tests
          [frontend_developer] Export button on Products page

 backend_developer  Created src/routers/products.py export endpoint
 backend_developer  Created tests/test_products.py — 4 new tests
 frontend_developer Created frontend/src/pages/ProductsPage.tsx — Export CSV button

 tech_lead  Reviewing against original spec...
 tech_lead  Score: 5/10 — N+1 database query, JSX parsing error
 tech_lead  Revision needed

 backend_developer  Fixed N+1 with selectinload, updated tests
 frontend_developer Fixed JSX structure, verified build

 tech_lead  Score: 9/10 — approved

 system  Branch: workermill/add-product-export (4 commits)
         Push and open PR? (y/n)
         Cost: ~$2.50 (planner + reviewer only — workers ran locally for free)

The reviewer caught a real N+1 database query. The workers fixed it. The re-review passed. No human intervention. That's the difference between one model approving its own work and a team with independent review.

Works with GitHub Issues (/build #42), Jira (/build PROJ-123), Linear (/build TEAM-42), spec files (/build spec.md), or just a description (/build add dark mode).

Review didn't pass? /retry picks up where you left off

> /retry

 coordinator  Retrying on branch: workermill/user-auth — 2 done, 1 remaining
 coordinator  Story 1/1: [backend_developer] Auth service

 backend_developer  Modified src/routes/auth.ts — cookie-based token, blacklist on /logout
 backend_developer  Modified src/middleware/requireAuth.ts — read token from cookie
 backend_developer  Running quality gates... vitest ✓ (23 passed)

 tech_lead  Score: 9/10 — approved

/retry doesn't start over. It loads the existing plan from disk, skips planning entirely, and resumes from the first incomplete story. No wasted tokens replanning or rebuilding what already works.

Review your code. Fix what it finds.

/review runs a standalone Tech Lead review on your current work. If it finds issues, WorkerMill offers to create a GitHub issue with the findings and immediately kicks off /build to fix them.

> /review branch

 tech_lead  Reading diff against main... 14 files changed
 tech_lead  Score: 6/10
 tech_lead  Issues:
   1. API key passed as query parameter — use headers
   2. No input validation on POST /api/webhooks
   3. Error responses leak stack traces in production

 Create a GitHub issue with these findings and fix them? (y/n) y

 coordinator  Created issue #18 — starting fix...

Works with branch (full diff vs main), diff (uncommitted changes), or a PR number (/review #42).

Target a single expert

/as sends one specialist with full tool access — no planning step, no review loop.

/as security_engineer audit this repository for injection and broken auth
/as backend_developer add pagination to the /api/tasks endpoint
/as devops_engineer set up a GitHub Actions CI pipeline
/as qa_engineer write integration tests for the checkout flow

Or just chat

Ask it to fix a bug, explain a function, or refactor a module. It reads your code, makes changes, runs your tests.

How It Works

Unlike single-model tools, WorkerMill never lets the same model review its own code.

1. A planner reads your codebase and decomposes the task into scoped stories with specific files and implementation guidance.
2. A critic (optional) scores the plan 1-10 on completeness, feasibility, and risk — refining it up to 3 times until it passes. Bad plans get caught before a single line of code is written.
3. Specialist workers build one story at a time — a backend expert writes the API, a frontend expert wires the UI. Workers run on local models, affordable cloud APIs, or any provider you choose.
4. Quality gates run after each story — your tests, linter, LSP diagnostics. Failures get injected into the reviewer's context.
5. A reviewer on a different model reads the actual diffs against the original spec. It rejects bad work with specific feedback — including real code examples — until the code meets the standard.

{
  "providers": {
    "ollama": { "model": "qwen3-coder:30b" },
    "openai": { "apiKey": "{env:OPENAI_API_KEY}" },
    "google": { "apiKey": "{env:GOOGLE_API_KEY}" }
  },
  "default": "ollama",
  "routing": {
    "planner": "openai",
    "tech_lead": "google"
  }
}

Use expensive models for judgment. Free local models for volume.

Features

AI Provider Support

Bring your own keys. Mix and match per role. WorkerMill uses the Vercel AI SDK — any compatible provider works out of the box.

Any provider with an OpenAI-compatible API also works — just add a host field in your config.

Commands

Shortcuts: !command runs shell directly · ESC cancels · ESC ESC rolls back last exchange · Shift+Tab cycles permission mode · @file.ts inlines code · @dir/ inlines tree · @url fetches content · @image.png sends to vision models

Context Windows

WorkerMill supports a shorthand context argument on /model commands for local providers. You do not pass a separate flag. Just append the context size after the model:

/model ollama/qwen3-coder:30b 32k
/model ollama/qwen3-coder:30b 256k
/model lmstudio/deepseek-coder-v2 64k

Accepted formats include values like 32k, 128k, 256k, and 1m.

For local providers like Ollama and LM Studio, this is the easiest way to raise or lower the working context without editing config by hand. If you prefer to set it in config, use the numeric contextLength field:

{
  "providers": {
    "ollama": {
      "model": "qwen3-coder:30b",
      "contextLength": 131072
    }
  }
}

The slash command shorthand and the config value represent the same setting for local providers; the command just lets you express it in a human-friendly form.

Built-in Personas

WorkerMill ships with 11 specialist personas. Each has its own system prompt, tool restrictions, and domain expertise — and each can be routed to a different provider via the routing config — run workers on Ollama for free, on affordable cloud models like Groq or DeepSeek, or on any provider you prefer.

Create your own by dropping a .md file in .workermill/personas/ (project) or ~/.workermill/personas/ (global). See all available personas with /personas.

Tools

WorkerMill gives its agents 23 tools — file operations, shell, search, git, web, code intelligence, memory, and tickets:

Plus any tools connected via MCP servers.

MCP Support

Connect external tools via the Model Context Protocol. WorkerMill supports stdio, HTTP, and SSE transports with lazy initialization — servers only spawn when their tools are first used.

{
  "mcp": {
    "servers": {
      "my-server": {
        "command": "npx",
        "args": ["-y", "my-mcp-server"]
      }
    }
  }
}

Auto-detects Docker Desktop MCP tools when available. Check status with /mcp.

Configuration

WorkerMill stores config at ~/.workermill/cli.json with project-level overrides in .workermill/config.json.

{
  "providers": {
    "anthropic": {
      "model": "claude-sonnet-4-6",
      "apiKey": "{env:ANTHROPIC_API_KEY}"
    },
    "ollama": {
      "model": "qwen3-coder:30b",
      "host": "http://localhost:11434",
      "contextLength": 65536
    }
  },
  "default": "ollama",
  "routing": {
    "planner": "anthropic",
    "tech_lead": "anthropic",
    "backend_developer": "ollama",
    "frontend_developer": "ollama"
  }
}

API keys support {env:VAR_NAME} syntax to read from environment variables. See Configuration docs for every field.

Documentation

• Commands — every slash command, subcommand, and flag
• Configuration — every field in ~/.workermill/cli.json with examples
• Personas — writing custom expert roles, tool restrictions, per-project overrides, provider routing
• Hooks & Custom Commands — shell hooks around tool calls, lifecycle events, custom slash commands
• Quality Gates — how verification commands, LSP diagnostics, and spec checks work
• Recipes — concrete workflows: mixed-provider teams, quality gates, local-only setups
• Troubleshooting — common issues, diagnostics, and fixes
• Architecture — how the CLI is put together
• Contributing — dev setup and PR guidelines

Contributing

PRs welcome. See Contributing for dev setup and guidelines.

Join the conversation in Discussions.

Apache License 2.0 — see LICENSE for details.