local-coder-mcp

Global MCP bridge for keeping Claude focused on reasoning, architecture, sensitive decisions, and review while delegating bounded implementation and context preprocessing to local Ollama models.

Architecture

User task
   |
   +--> deterministic work --------------------------> normal tools
   |
   +--> prepare_local_context -----------------------> compact file:line capsule
   |                                                     |
   |                                                     v
   +-------------------------------------------------- Claude decides
                                                         |
                  +-------------------+------------------+------------------+
                  |                   |                                     |
               normal local      local-supervised                         Claude
                  |                   |                                     |
                  |          sensitive decision already                     |
                  |          resolved by Claude                             |
                  |                   |                                     |
                  +---------+---------+                                     |
                            |                                               |
                 compact task / Claude-planned feature                     |
                            |                                               |
                 Ollama edit -> validate -> retry                          |
                            |                                               |
                    compact review capsule                                 |
                            |                                               |
                full diff mandatory if supervised                          |
                            +---------------------> Claude final review <----+

Related MCP server: Ollama MCP Server

v0.6 capabilities

The server exposes twelve MCP tools:

• local_coder_health

• classify_local_code_task

• discover_local_workspace

• search_local_workspace

• prepare_local_context

• delegate_code_task

• execute_local_code_task

• execute_local_code_task_compact preferred

• execute_local_code_plan

• execute_local_code_plan_compact preferred

• get_local_run

• local_coder_telemetry

Four routing classes

classify_local_code_task now returns one of:

• deterministic — existing tooling is better than any LLM;

• local — bounded implementation with known approach;

• local-supervised — sensitive domain, but Claude already resolved the sensitive behavior and only bounded implementation remains;

• claude — reasoning, architecture, discovery, or risk is still unresolved.

The key v0.6 rule is:

classify the work that remains, not merely the domain touched.

Authentication, authorization, credentials, permissions, sessions, tokens, and secrets no longer automatically force all implementation into Claude.

Claude must first resolve the relevant sensitive behavior/contract. After that, a bounded implementation can be routed with:

{
  "solutionKnown": true,
  "validationKnown": true,
  "sensitiveDecisionResolved": true,
  "riskTags": ["auth", "credentials"]
}

A local-supervised result means:

Claude decides sensitive behavior
        ↓
local model implements only that bounded decision
        ↓
validation/retry stays local
        ↓
full diff is mandatory
        ↓
Claude reviews before approval

local-supervised does not allow the local model to redesign auth/security behavior.

Cryptography design, unresolved architecture/discovery, unknown-root-cause debugging, destructive migrations, production infrastructure, concurrency, and similar work remain Claude blockers.

Token Killer

Compact execution results

execute_local_code_task_compact and execute_local_code_plan_compact persist complete execution results under:

~/.local-coder-mcp/runs/<runId>/run.json
~/.local-coder-mcp/runs/<runId>/diff.patch

Claude initially receives a compact result containing status, validation summary, routing/review metadata, changed-file counts, local token/latency data, and runId.

Use get_local_run with summary, diff, validation, or full only when needed. Results are paginated.

For local-supervised, the compact result explicitly requires Claude to fetch and review the full stored diff before approval.

Context capsules

prepare_local_context maintains a persistent local repository index under:

~/.local-coder-mcp/indexes/

It ranks likely relevant files and returns bounded path:startLine-endLine evidence so Claude does not need to broadly read the repository before every task.

Review capsules

Compact execution returns deterministic review metadata including:

• additions/deletions;

• changed-file count;

• risk level;

• review targets;

• validation state;

• dependency/package signals;

• export/suppression signals;

• security/environment/migration/infra signals;

• fullDiffRecommended.

Normal low-risk validated work can stay compact. Supervised-sensitive work always forces full-diff review.

Large-feature orchestration

For dashboards, modules, multi-screen features, or other broad implementation:

1. Claude understands requirements and architecture.

2. Claude resolves sensitive/product decisions.

3. Claude decomposes into bounded subtasks, normally 1–5 editable files each.

4. Normal subtasks route local.

5. Sensitive subtasks whose decisions are already resolved route local-supervised.

6. execute_local_code_plan_compact validates the dependency DAG and routing before editing.

7. Tasks execute sequentially through the bounded local executor.

8. Each task validates and retries locally.

9. Final integration validation runs after all tasks succeed.

10. Failure rolls the whole feature back by default.

11. Any supervised subtask forces full aggregate-diff Claude review.

The local model never owns large-feature decomposition or sensitive design decisions.

Safety boundaries

• absolute workspace required;

• relative file paths only;

• path traversal rejected;

• symlink escapes rejected;

• .git, node_modules, .ssh, and real .env* secrets blocked;

• .env.example, .env.sample, and .env.template allowed;

• explicit editable-file allowlists;

• bounded file/context sizes;

• validation commands supplied by Claude, never invented by the local model;

• validation runs with shell: false;

• default executable allowlist: npm,pnpm,yarn,bun;

• failed bounded tasks roll back by default;

• failed plans roll back the full plan by default;

• supervised-sensitive execution injects a constraint forbidding redesign of sensitive contracts.

Claude-side token saver

Install/update:

npm run install:claude-token-saver

It backs up ~/.claude/settings.json, enables deferred MCP Tool Search, caps MCP output, installs a PostToolUse hook that compacts only large successful validation output, and adds this user-level permission:

{
  "permissions": {
    "allow": ["mcp__local-coder__*"]
  }
}

The installer preserves existing permissions.allow, permissions.ask, and permissions.deny entries and is idempotent. Claude Code evaluates permission rules in deny -> ask -> allow order across settings scopes, so a matching project or managed ask/deny rule can still override the user-level local-coder allowlist. Use /permissions to identify the source if prompts continue.

It deliberately does not lower Claude thinking-token settings.

Global routing policy

Install/update:

npm run install:routing

This installs:

~/.claude/rules/local-coder.md

The v0.6 rule explicitly teaches Claude that auth/security domain presence is not itself an implementation blocker: Claude resolves the sensitive decision first, then delegates the mechanical remainder as local-supervised with mandatory full-diff review.

Telemetry

Aggregate telemetry is stored locally at:

~/.local-coder-mcp/telemetry.jsonl

It records route/status/attempt/task/token/duration/count metadata, not prompts or source code. Classification telemetry distinguishes local-supervised from ordinary local work.

Requirements

• Node.js 20+

• Ollama running locally

• qwen2.5-coder:14b installed, or another LOCAL_CODER_MODEL

• Claude Code Desktop / Code tab with local MCP support

Install / update

Existing clone:

git switch main
git pull
npm install
npm run check
npm run build
npm run install:routing
npm run install:claude-token-saver

If the MCP already points at the same dist/index.js, npm run install:claude is not required again.

For first setup:

npm run install:claude
npm run install:routing
npm run install:claude-token-saver

Fully quit and reopen Claude Code Desktop after changing user-level Claude configuration.

Test without Claude

npx @modelcontextprotocol/inspector \
  "$(which node)" \
  "$(pwd)/dist/index.js"

Useful v0.6 classifier test:

{
  "task": "Implement the already-decided credential removal behavior and update its tests.",
  "solutionKnown": true,
  "validationKnown": true,
  "estimatedFiles": 3,
  "riskTags": ["auth", "credentials"],
  "sensitiveDecisionResolved": true
}

Expected route:

local-supervised

The same request without sensitiveDecisionResolved: true should remain in Claude.

Configuration

Benchmark

LOCAL_CODER_MODEL=qwen2.5-coder:14b npm run benchmark -- benchmarks/my-real-tasks.json

Use disposable worktrees.

Roadmap

• MCP + Ollama bridge

• bounded local executor

• validation/retry/rollback

• deterministic/local/Claude routing

• local-supervised sensitive execution routing

• mandatory full-diff supervised review

• workspace discovery/search

• multi-task transactional orchestrator

• telemetry + benchmark harness

• compact/lazy execution results

• deterministic review capsules

• persistent context index + file:line context capsules

• compact global Claude rule

• Claude-side MCP output/tool-search guardrails

• local-coder MCP permission allowlist installer

• successful validation-output compaction hook

• benchmark candidate local models on the same real repository suite and choose the measured default

License

MIT