speed-run
CLAUDE.md1 starsChanged 4 months agoMITView on GitHub
Speed-run offloads first-pass code generation to Cerebras (~2000 tokens/sec), then Claude handles architecture decisions and surgical fixes. Same quality code, ~60% fewer Claude tokens, 20x faster generation per file. Most code is pattern-following, not reasoning. Cerebras handles the patterns; Claude handles the thinking. Get a free key at https://cloud.cerebras.ai Set it using either method: Option A (recommended): Add to ~/.claude/settings.json: Option B: Export in shell profile (~/.zshrc or ~/.bashrc): Restart Claude Code after setting the key. The plugin checks on…
- Reads credentials
- Installs packages
In this repository5 other files it gives its agents.
- any-percentSkill
- judgeSkill
- showdownSkill
- speed-runSkill
- turboSkill
The file
We split this CLAUDE.md into the rules it gives an agent
12 rules. About 0 are common, 6 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 42
Option A (recommended): Add to ~/.claude/settings.json:
- Distinctive: line 83
Write a contract prompt (DATA CONTRACT, API CONTRACT, ALGORITHM, RULES)
- Very specific: line 84
Call mcp__speed-run__generate_and_write_files with the prompt
- Distinctive: line 86
If tests fail, Claude fixes surgically (don't regenerate the whole thing)
- Distinctive: line 99
Write a shared design document
- Distinctive: line 114
Write a plan document defining each approach
- Distinctive: line 120
Best for: When you genuinely don't know which approach is right and want to let the code speak.
- Very specific: line 157
If generated code contains literal triple backticks, use TRIPLE_BACKTICK as a placeholder - the server auto-replaces after extraction.
- Very specific: line 171
Use test-kitchen when first-pass quality matters most.
- Distinctive: line 185
Don't re-prompt Cerebras when tests fail.
- Very specific: line 191
Don't use speed-run for tasks that require actual reasoning about architecture or tradeoffs.
- Very specific: line 193
If tools aren't working, you probably forgot the API key.
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Speed-Run Plugin
Overview
Speed-run offloads first-pass code generation to Cerebras (~2000 tokens/sec), then Claude handles architecture decisions and surgical fixes. Same quality code, ~60% fewer Claude tokens, 20x faster generation per file.
Most code is pattern-following, not reasoning. Cerebras handles the patterns; Claude handles the thinking.
Architecture
┌─────────────────────────────────────────────┐
│ speed-run (orchestrator skill) │
│ Checks API key → routes to sub-skill │
├──────────┬──────────┬───────────────────────┤
│ turbo │ showdown │ any-percent │
│ 1 task │ N runners│ N approaches │
│ direct │ same spec│ different specs │
└────┬─────┴────┬─────┴────┬──────────────────┘
│ │ │
v v v
┌─────────────────────────────────────────────┐
│ MCP Server (@2389/speed-run-mcp) │
│ ┌───────────┬──────────────┬─────────────┐ │
│ │ generate │ generate_and │ check_status│ │
│ │ │ _write_files │ │ │
│ └─────┬─────┴──────┬───────┴─────────────┘ │
│ │ │ │
│ v v │
│ Cerebras API (gpt-oss-120b) │
└─────────────────────────────────────────────┘Prerequisites
CEREBRAS_API_KEY
Get a free key at https://cloud.cerebras.ai
Set it using either method:
Option A (recommended): Add to ~/.claude/settings.json:
{
"env": {
"CEREBRAS_API_KEY": "your-key-here"
}
}Option B: Export in shell profile (~/.zshrc or ~/.bashrc):
export CEREBRAS_API_KEY="your-key-here"Restart Claude Code after setting the key. The plugin checks on session start via a hook and warns if the key is missing.
MCP Server
The MCP server auto-registers via .mcp.json when the plugin is installed. If mcp__speed-run__* tools aren't available, build manually:
cd ./mcp && npm install && npm run buildSkills
Routing
| Skill | Trigger | What it does |
speed-run | "speed-run", "turbo", "fast codegen", "cerebras" | Orchestrator. Checks API key, presents options. |
speed-run:turbo | Single task, straightforward codegen | Direct generation. One contract prompt, one output. |
speed-run:showdown | Multiple implementations of the same spec | Parallel competition. N runners implement the same design, judge picks the winner. |
speed-run:any-percent | Multiple architectural approaches | Parallel exploration. N variants try different approaches, judge evaluates tradeoffs. |
speed-run:judge | Called by showdown/any-percent | Scoring framework. 5 criteria, 25 points max, hard gates on critical flaws. |
Turbo (Direct Codegen)
The simplest path. Use when you have one task and want fast generation.
Flow:
- Write a contract prompt (DATA CONTRACT, API CONTRACT, ALGORITHM, RULES)
- Call
mcp__speed-run__generate_and_write_fileswith the prompt - Run tests
- If tests fail, Claude fixes surgically (don't regenerate the whole thing)
- Re-test until green
Best for: Algorithmic code, boilerplate, data transformations, multi-file scaffolding.
Not great for: Novel architecture decisions, complex business logic, anything requiring deep reasoning about tradeoffs.
Showdown (Parallel Competition)
Same design doc, multiple runners implement it independently. The judge scores all variants and picks a winner.
Flow:
- Assess complexity → decide runner count (2-5)
- Write a shared design document
- Dispatch all runners in a single message (parallel agents)
- Each runner: hosted LLM generates → tests → Claude fixes
- Judge scores all variants (fitness, complexity, readability, robustness, maintainability)
- Winner gets promoted, losers get cleaned up
Critical: Dispatch all runners in a single message. Sequential dispatch defeats the purpose.
Any-Percent (Parallel Exploration)
Different architectural approaches to the same problem. Unlike showdown, each variant uses a different strategy.
Flow:
- Gather context about the problem
- Identify 2-5 distinct approaches (e.g., "event-driven vs polling vs hybrid")
- Write a plan document defining each approach
- Dispatch all variants in a single message
- Each variant: hosted LLM generates → tests → Claude fixes
- Judge evaluates tradeoffs across approaches
- Winner gets promoted
Best for: When you genuinely don't know which approach is right and want to let the code speak.
Judge (Scoring Framework)
Evaluates implementations across 5 criteria, each scored 1-5:
| Criterion | What it measures |
| Fitness for Purpose | Does it actually do what was asked? (8 checkboxes) |
| Justified Complexity | Is the complexity earned? (line count analysis) |
| Readability | Can someone else understand it? (violation counting) |
| Robustness & Scale | Will it hold up? (12-item checklist) |
| Maintainability | Can it evolve? (6-item checklist) |
Hard gates: Fitness delta >= 2 between variants, or any score of 1, triggers automatic disqualification.
MCP tools
| Tool | Purpose |
mcp__speed-run__generate | Send a prompt to Cerebras, get raw text back |
mcp__speed-run__generate_and_write_files | Send a prompt, parse file blocks from response, write to disk |
mcp__speed-run__check_status | Verify API key is set and Cerebras is reachable |
File output format
The MCP server parses generated code from XML-style tags:
<FILE path="src/main.py">
def hello():
print("hello world")
</FILE>Two legacy fallback formats (### FILE: path with fenced blocks, or raw content) are supported but not recommended.
If generated code contains literal triple backticks, use TRIPLE_BACKTICK as a placeholder - the server auto-replaces after extraction.
Speed-run vs test kitchen
| Aspect | Test Kitchen | Speed-Run |
| Code generation | Claude direct | Hosted LLM (Cerebras) |
| API key required | No | Yes (CEREBRAS_API_KEY) |
| Token cost | Standard Claude pricing | ~60% savings on generation |
| Generation speed | ~10s per file | ~0.5s per file |
| First-pass quality | ~100% correct | 80-95% (Claude fixes the rest) |
| Fix strategy | Rarely needed | Surgical fixes by Claude |
| Best for | Any task | Algorithmic code, boilerplate, multi-variant |
Use test-kitchen when first-pass quality matters most. Use speed-run when you want speed and token savings and don't mind a fix cycle.
Skill dependencies
| Dependency | Used By | Purpose |
speed-run:judge | showdown, any-percent | Scoring framework (bundled) |
superpowers:dispatching-parallel-agents | showdown, any-percent | Parallel dispatch |
superpowers:using-git-worktrees | showdown, any-percent | Isolated workspaces |
superpowers:verification-before-completion | all | Verify before claiming done |
fresh-eyes-review:fresh-eyes-review | showdown, any-percent | Quality gate before comparison |
Common mistakes
Don't re-prompt Cerebras when tests fail. Claude should read the error and fix it surgically. Cerebras already did the structural work -- regenerating from scratch wastes the effort.
Showdown and any-percent must dispatch all runners in a single message. Running them one at a time defeats the whole point of parallelism.
Turbo needs structured contract prompts (DATA CONTRACT, API CONTRACT, etc). If you send it a vague prompt, you get vague code back.
Don't use speed-run for tasks that require actual reasoning about architecture or tradeoffs. Cerebras is fast at following patterns, not at thinking. Use Claude directly for those.
If tools aren't working, you probably forgot the API key. The session-start hook warns on launch, but mcp__speed-run__check_status will confirm.
Configuration
| Variable | Default | Purpose |
CEREBRAS_API_KEY | (required) | API key from https://cloud.cerebras.ai |
CEREBRAS_MODEL | gpt-oss-120b | Model to use |
CEREBRAS_URL | https://api.cerebras.ai/v1 | API endpoint |
GENERATION_TIMEOUT | 120 | Timeout in seconds |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

