LABSCO SUMMARY

It puts an expensive model on the plan and the review, and leaves the cheap model to do the typing.

Your whole codebase goes into the context window by default — that is the design, and it is also why curate_context exists: run it first so a task only carries the directories it actually touches. Everything lands in GitHub, the plan as an issue and the judgement as a linked sub-issue, so the reasoning survives outside the chat window.

What it is

A planning and review server for coding agents. It sends your codebase to a big model to produce a detailed workplan, posts that as a GitHub issue, and later compares two git refs against the same plan.

What you get

create_workplan opens the GitHub issue immediately, then fills it in from a background run of the model over your codebase
revise_workplan re-runs that against your revision instructions and updates the same issue in place
get_workplan reads a plan back by issue number, and workplans are also exposed as MCP resources your client can list
judge_workplan compares two git refs, or a pull request, against the original plan and posts the verdict as a linked sub-issue
curate_context analyses the repository for a stated task and writes a .yellhorncontext file naming the directories worth sending to the model
Context control through .yellhornignore and .yellhorncontext, automatic chunking when a codebase outgrows the model's window, and Google Search grounding with Markdown citations on Gemini models
Cost estimation and usage tracking on every API call

Requirements

The GitHub CLI (gh), installed and authenticated — every workplan and every judgement is a GitHub issue. A key for the model family you pick: GEMINI_API_KEY, OPENAI_API_KEY or XAI_API_KEY. YELLHORN_MCP_MODEL selects the model (default gemini-2.5-pro, with GPT-5, o3, Grok-4 and deep-research options), YELLHORN_MCP_REASONING_EFFORT sets low, medium or high on GPT-5 models, and YELLHORN_MCP_SEARCH turns search grounding on or off. REPO_PATH points at the repository and defaults to the current directory. Install with uv pip install yellhorn-mcp and run it over stdio as uv run yellhorn-mcp.

Setup effort

One command plus a key — uv pip install yellhorn-mcp, then supply credentials

See installation options

USE CASES

01

Turning a vague feature request into something buildable

Describe the task; the issue appears at once and fills in with a plan drawn from the whole codebase.

create_workplan

02

Handing a coding agent something concrete to work from

Fetch the plan by issue number and pass it straight into the agent's context.

get_workplan

03

Checking that what got built is what was asked for

Compare the branch against the base ref and read the verdict on the linked sub-issue.

judge_workplan

04

Keeping the model's context to the part of the repo that matters

Analyse the tree for your task and write the directory list before paying for a long run.

curate_context

05

Updating a plan after the requirements moved

Give the revision instructions; the same issue is rewritten rather than replaced.

revise_workplan

5 tools

Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.

`create_workplan`

Creates a GitHub issue with a detailed implementation plan.

This tool will:

Create a GitHub issue immediately with the provided title and description
Launch a background AI process to generate a comprehensive workplan
Update the issue with the generated workplan once complete

The AI will analyze your entire codebase (respecting .gitignore) to create a detailed plan with:

Specific files to modify/create
Code snippets and examples
Step-by-step implementation instructions
Testing strategies

Codebase reasoning modes:

"full": Complete file contents (most comprehensive)
"lsp": Function signatures and docstrings only (lighter weight)
"file_structure": Directory tree only (fastest)
"none": No codebase context

Returns the created issue URL and number immediately.

BEFORE YOU INSTALL

What to know first

Tools you get

5 tools when we connected.

Requires

uv on PATH
One of GEMINI_API_KEY, OPENAI_API_KEY or XAI_API_KEY in your environment — the key for the model you pick

Where it runs

All 3 documented clients run the server on your machine.

CONTEXT COST

Light Standing cost

Rated by the size of the 5 tool definitions that ride along on every turn, not by how many there are

INSTALLATION

Connect your client

Server setup

TERMINAL

uv pip install yellhorn-mcp

MCP Clients

Codex

CODEX · TOML

[mcp_servers.yellhorn-mcp]
command = "uv"
args = ["run", "yellhorn-mcp"]

[mcp_servers.yellhorn-mcp.env]
GEMINI_API_KEY = "<YOUR_GEMINI_API_KEY>"
REPO_PATH = "<YOUR_REPO_PATH>"

Only one provider key is needed — the one for the model you run. Each block already sets one (GEMINI_API_KEY, or OPENAI_API_KEY with --model o3); to use a Grok model, swap in XAI_API_KEY and set the model.

VS Code

VS CODE · JSON

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gemini-api-key",
      "description": "Gemini API Key"
    }
  ],
  "servers": {
    "yellhorn-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "yellhorn-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "${input:gemini-api-key}",
        "REPO_PATH": "${workspaceFolder}"
      }
    }
  }
}

Only one provider key is needed — the one for the model you run. Each block already sets one (GEMINI_API_KEY, or OPENAI_API_KEY with --model o3); to use a Grok model, swap in XAI_API_KEY and set the model.

Claude Code

CLAUDE CODE · JSON

{
  "mcpServers": {
    "yellhorn-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "yellhorn-mcp",
        "--model",
        "o3"
      ],
      "env": {
        "YELLHORN_MCP_SEARCH": "on",
        "OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>"
      }
    }
  }
}

Only one provider key is needed — the one for the model you run. Each block already sets one (GEMINI_API_KEY, or OPENAI_API_KEY with --model o3); to use a Grok model, swap in XAI_API_KEY and set the model.

Yellhorn MCP

It puts an expensive model on the plan and the review, and leaves the cheap model to do the typing.

What it is

What you get

Requirements

Setup effort

Turning a vague feature request into something buildable

Handing a coding agent something concrete to work from

Checking that what got built is what was asked for

Keeping the model's context to the part of the repo that matters

Updating a plan after the requirements moved

5 tools

`create_workplan`

`curate_context`

`get_workplan`

`judge_workplan`

`revise_workplan`

What to know first

Tools you get

Requires

Where it runs

Light Standing cost

Connect your client

Server setup

MCP Clients

Codex

VS Code

Claude Code

Yellhorn MCP

It puts an expensive model on the plan and the review, and leaves the cheap model to do the typing.

What it is

What you get

Requirements

Setup effort

Turning a vague feature request into something buildable

Handing a coding agent something concrete to work from

Checking that what got built is what was asked for

Keeping the model's context to the part of the repo that matters

Updating a plan after the requirements moved

5 tools

create_workplan

curate_context

get_workplan

judge_workplan

revise_workplan

What to know first

Tools you get

Requires

Where it runs

Light Standing cost

Connect your client

Server setup

MCP Clients

Codex

VS Code

Claude Code

Same category

Software Planning Tool

Nexus Agents Control Plane

Intent-Driven Development

Railagent

`create_workplan`

`curate_context`

`get_workplan`

`judge_workplan`

`revise_workplan`