pedalpoint

Route mechanical development tasks to a local LLM (MLX on Apple Silicon, or Ollama) via Claude Code, so your Claude session goes further. Automatically falls back to local-only mode when Claude quota is exhausted.

What it does

• Hybrid routing: Claude classifies each task. Mechanical work (scaffolding, CRUD, test stubs) goes to your local LLM. Judgment work (architecture, debugging, integration) stays with Claude.
• Three-tier quota fallback: When Claude Pro returns a quota error, pedalpoint first routes judgment and structural tasks to Claude API (pay-per-token) while mechanical tasks continue on local LLM. If the API key is absent or Claude API quota is also exhausted, all tasks fall back to local LLM. Restores to normal when quota recovers.
• Context Courier: Before sending any task to the local LLM, pedalpoint greps your codebase for existing patterns and passes those files to the server. Local LLMs only get tasks they have templates for.
• Drafts, not re-typing: The server writes the local model's output straight to <file>.draft (only inside the current git repo). Claude reads it, fixes what's wrong, and promotes it with mv — it never re-types the code, which is where the token savings come from.
• Proof: pedalpoint stats reports net Claude output tokens saved per model per week, using real token counts from Claude Code transcripts.
• Single install: One script installs the MCP server, pulls the default model, and registers the companion skill.

Requirements

• Claude Code
• Python 3.11+
• Apple Silicon: mlx-lm (installed by the script), or
• Elsewhere: Ollama (or any OpenAI-compatible inference server)

Install

curl -fsSL https://raw.githubusercontent.com/EMSwank/pedalpoint/main/install.sh | sh

The backend defaults to mlx on Apple Silicon and ollama elsewhere. To choose explicitly, or use a custom model or endpoint:

curl -fsSL https://raw.githubusercontent.com/EMSwank/pedalpoint/main/install.sh | \
  sh -s -- --backend ollama --model llama3 --base-url http://localhost:11434/v1

Existing installs keep working as Ollama. Re-run with --backend mlx to switch.

Restart Claude Code after install.

Note: If installing without the script, use uv tool install pedalpoint — not pip install -e .. The tool install puts pedalpoint-server in PATH where Claude Code can find it.

Usage

MLX starts itself. The first local_llm call starts mlx_lm.server (that call takes ~10s longer while the model loads) and it stops after 20 minutes with no calls from any Claude Code session, freeing its ~5GB. A server you start by hand is used as-is and never stopped. Set PEDALPOINT_AUTOSTART=0 to always manage it yourself:

mlx_lm.server --model mlx-community/gemma-4-e4b-it-4bit   # backend mlx, manual
ollama serve                                              # backend ollama (or open Ollama.app)

Ollama already unloads idle models on its own (OLLAMA_KEEP_ALIVE, default 5 minutes).

Then in any Claude Code session:

/route-tasks

pedalpoint handles routing automatically. No manual flagging needed.

To verify the MCP server connected:

claude mcp get pedalpoint

Should show Status: ✓ Connected. If disconnected, run pedalpoint-server directly to see the error.

Modes

Configuration

Choosing a model

Measured on a 16GB M4 MacBook Air with normal apps open (four pedalpoint-style coding tasks, two runs):

Download a different MLX model with uvx --from huggingface_hub hf download <repo>, set PEDALPOINT_MODEL, and restart Claude Code (an auto-started server picks up the new model the next time it starts). pedalpoint stats shows whether a model pays off on your real work.

Measuring savings

pedalpoint stats            # last 7 days
pedalpoint stats --days 30

For each model and week: handoffs, average score (1–7, what Claude had to do with the draft), redo rate, local tokens, net Claude output tokens saved, input overhead, and the share of rows estimated rather than measured. Rows flagged NOT PAYING OFF have an average score under 5 or a net saving ≤ 0. Handoffs are logged to ~/.pedalpoint/handoffs.jsonl.

Uninstall

curl -fsSL https://raw.githubusercontent.com/EMSwank/pedalpoint/main/install.sh | sh -s -- --uninstall

Troubleshooting

Development

git clone https://github.com/EMSwank/pedalpoint
cd pedalpoint
uv sync --extra dev   # or: pip install -e ".[dev]"
pytest tests/unit/ -v

Integration tests (require a running model server):

PEDALPOINT_INTEGRATION=true PEDALPOINT_BACKEND=ollama pytest tests/integration/test_ollama.py -v
PEDALPOINT_INTEGRATION=true PEDALPOINT_BACKEND=mlx pytest tests/integration/test_mlx.py -v

Install script tests (requires bats-core):

brew install bats-core   # macOS; use apt-get install bats on Linux
bats tests/install/

License

MIT