TL;DR: Install with claude plugin install godmode. Say /godmode optimize my API and walk away. It measures, iterates, keeps improvements, reverts failures, and stops when done.

See It In Action

Real captures from live pi sessions (zai/glm-5.3, recorded with vhs) — tapes and targets in demo/.

1. Skill routing — request to matched skill

godmode Tier-1 matching routes a checkout rate-limiting request to the ratelimit skill.

Real session excerpt — demo/tapes/skill-routing.tape (recorded 2026-08-27, pi 0.84.3, zai/glm-5.3)

$ timeout 240 pi -p -ne --model zai/glm-5.3 \
    --skill ~/.pi/agent/skills/godmode/godmode/SKILL.md "Route only. The user request is: \
    we keep getting rate limited by the payment provider during checkout. [...]"

Tier 1 match complete.

- **Stack detected:** Godmode skill-plugin repo (skills/ + agents/, no runtime app code in scope)
- **Tier 1 hits:** `ratelimit` ("rate limit", "throttle", 429 — direct match); `pay` (payments context, secondary)
- **Phase:** THINK — rate limiting against a third-party provider is a design problem (client-side throttle/queue/backoff) before any build

`DISPATCH: skill=ratelimit phase=THINK (secondary=pay) task=rate-limited-by-payment-provider-at-checkout`

ROUTED_OK

$ git status --short
(no output — the routing session modified nothing)

2. Optimize loop — real keep, real revert

baseline 189ms, lru_cache KEEP at 0ms, fib(32) regression DISCARD at 517ms, reverted with git reset — real metric, real revert.

Real session excerpt — demo/tapes/optimize-loop.tape (recorded 2026-08-27, pi 0.84.3, zai/glm-5.3)

$ python3 -m unittest -q test_slow_fib
Ran 1 test in 0.230s
OK

$ bash metric.sh && bash metric.sh && bash metric.sh      # timing runs — the session derives its own baseline below
278
217
211

$ timeout 300 pi -p -ne --model zai/glm-5.3 \
    --skill ~/.pi/agent/skills/godmode/optimize/SKILL.md "Setup answers: Goal = reduce the \
    runtime of work() in slow_fib.py. [...] Test exactly these two hypotheses in order: \
    (1) add functools lru_cache memoization to fib; (2) remove the lru_cache decorator and \
    change work() to return fib(32), claiming batch amortization. [...] A DISCARD must be \
    reverted with git reset --hard HEAD~1. [...]"

**Session complete** — baseline 189 ms → best 0 ms (−100%).

- **Baseline:** median 189 ms (3 runs, variance <5%)
- **R1 · H1 KEEP:** @lru_cache(maxsize=None) on fib → 0 ms (0,0,0), guard OK (work()=832040)
- **R2 · H2 DISCARD:** removed cache, work()=fib(32) → 517 ms AND guard failed (2178309 ≠ 832040); reverted via git reset --hard HEAD~1
- Stop: budget exhausted (2 rounds); kept commit 0c162a0; lessons + failures logged in .godmode/*

$ cat .godmode/optimize-results.tsv
round	agent	change	metric_before	metric_after	delta_pct	status	failure_class
0	baseline	initial measurement	-	189	-	baseline	-
1	1	add lru_cache(maxsize=None) to fib	189	0	-100.0	KEEP	-
2	1	remove lru_cache, work()=fib(32) batch amortization	0	517	+51700.0	DISCARD	guard_fail+metric_regression

$ git log --oneline
d26b093 (HEAD -> master) round2 discard logged; session complete
7b6bc53 round1 keep: 189ms -> 0ms
0c162a0 round1: add functools.lru_cache memoization to fib
230bf5e iteration 0: baseline metric 189ms
2e2ab07 baseline

OPT_DONE

3. Goal-bridge — machine-checkable completion contract

a failing test goes red to green under a 4-field contract (metric / threshold / evidence / rollback) with exit-0 proof.

Real session excerpt — demo/tapes/goal-bridge.tape (recorded 2026-08-27, pi 0.84.3, zai/glm-5.3)

$ python3 -m unittest -q test_counter                  # baseline: real failure (red)
FAILED (failures=2) — AssertionError: 1 != 0 (total([])), AssertionError: 7 != 6 (total([1, 2, 3])) — off-by-one (result = 1)

$ timeout 240 pi -p -ne --model zai/glm-5.3 \
    --skill ~/.pi/agent/skills/godmode/goal-bridge/SKILL.md "Goal: make the test suite pass. \
    Derive the Goal-Bridge contract FIRST and print its exact 4-field block: metric, \
    threshold, evidence, rollback. [...] Then fix counter.py, run the metric each round \
    appending to the evidence file, and stop as soon as it exits 0. [...]"

Metric exited 0 → **DONE** (round 2/3, rollback never fired).

Goal-Bridge Contract (mandatory final output):
- metric: python3 -m unittest -q test_counter
- threshold: exit 0
- evidence: .godmode/goal-evidence.txt
- rollback: metric fails 2 consecutive rounds

Summary:
- Round 1: metric exit=1 (2 failures) → appended to evidence; fixed `counter.py` off-by-one (`result = 1` → `result = 0`)
- Round 2: metric exit=0 (`OK`, 2 tests) → appended to evidence; stopped
- Rollback trigger: never fired (max 1 consecutive failure); no revert needed
- Files written: `counter.py` (edit), `.godmode/goal-evidence.txt` (new)

$ cat .godmode/goal-evidence.txt
=== Round 1: 2026-08-27T21:40:11Z ===
exit=1
=== Round 2: 2026-08-27T21:40:15Z ===
exit=0

$ python3 -m unittest -q test_counter && echo "CONTRACT MET — exit 0"
CONTRACT MET — exit 0

The three captures above are real sessions; the blocks below are illustrative output shapes of other skills — not captured transcripts.

$ /godmode:optimize
Goal: Reduce API response time
Iterations: 20

  BASELINE    847ms
  ROUND 1     554ms  KEPT  (-34.5%)  -- added index on category_id
  ROUND 2     382ms  KEPT  (-31.0%)  -- enabled gzip compression
  ROUND 3     276ms  KEPT  (-27.7%)  -- eager loading for posts
  ROUND 4     290ms  REVERTED        -- batch loader (guard failed)
  ROUND 5     226ms  KEPT  (-18.2%)  -- connection pool to 20
  ROUND 6     198ms  KEPT  (-12.4%)  -- Redis response cache

  === 847ms --> 198ms (76.6% improvement) ===
  Keeps: 5 | Discards: 1

$ /godmode:build
Goal: Add user authentication system

  PLAN        Decomposed into 4 parallel tasks
  AGENT 1     [worktree] Auth middleware + JWT tokens        DONE
  AGENT 2     [worktree] User model + password hashing       DONE
  AGENT 3     [worktree] Login/register API endpoints         DONE
  AGENT 4     [worktree] Integration tests for auth flow      DONE
  MERGE       Sequential merge + test after each              ALL PASS
  REVIEW      4-agent code review (security, perf, style)     APPROVED

  === 4 tasks | 4 agents | 12 files | 47 tests passing ===

$ /godmode:secure
Target: src/api/

  RECON       Mapped 23 endpoints, 4 auth flows, 2 data stores
  STRIDE      6 threat categories analyzed
  OWASP       Top 10 checklist applied
  RED TEAM    4 personas: script kiddie, insider, APT, researcher

  CRITICAL  1   SQL injection in /api/search (parameterize query)
  HIGH      2   Missing rate limit on /api/login, weak CORS policy
  MEDIUM    3   Verbose error messages, missing CSP header, session fixation
  LOW       1   Server version disclosed in headers

  7 findings with fix code + verification commands

Quick Start

# Install (Claude Code)
claude plugin install godmode

# Or install for other platforms
bash adapters/codex/install.sh
bash adapters/cursor/install.sh
bash adapters/gemini/install.sh
bash adapters/opencode/install.sh
bash adapters/pi/install.sh

# Use specific skills
/godmode:optimize   # Autonomous performance iteration
/godmode:build      # Build with parallel agents
/godmode:secure     # Security audit
/godmode:ship       # Pre-flight + deploy + verify

# Or just describe what you want
/godmode make this API faster       # --> routes to optimize
/godmode fix the failing tests      # --> routes to fix
/godmode build a rate limiter       # --> routes to think --> plan --> build

Godmode auto-detects what you need and routes to the right skill.

What Is Godmode?

Godmode is an open-source plugin that adds autonomous coding capabilities to AI assistants like Claude Code, Cursor, Codex, Gemini CLI, and OpenCode. Instead of generating code once and hoping it works, Godmode runs a disciplined engineering loop: measure, modify, verify, keep or revert, repeat — until the goal is met.

It ships with 135 expert skills across 13 domains (performance optimization, security auditing, TDD, deployment, database tuning, and more), 7 specialized subagents that work in parallel, a failure memory system that learns from every discarded change, and a built-in authoring-discipline prelude that prevents the most common LLM coding mistakes before they hit the repo.

How Godmode Compares to Plain AI Coding

Benchmark

The repo benchmarked itself against a plain agent on 30 small tasks — 2 runs each, same model (zai/glm-5.3) in both arms, identical prompt. Godmode passed 60/60 scored runs; the plain agent passed 58/60. The plain agent was faster on median wall-clock (37.0s vs 41.0s), and the verify gate passed 48/48 checks over 24 of the 60 godmode passes.

The honest breakdown — including where the plain agent won and why the pass difference is within noise — is in the showdown post.

How It Works

Every iterative skill follows the same disciplined loop:

1. REVIEW   -- read state, logs, git history
2. IDEATE   -- pick the next change (informed by past failures)
3. MODIFY   -- make ONE atomic change, commit before verify
4. VERIFY   -- run guard (tests + lint + build must all pass)
5. DECIDE   -- improved --> KEEP. Worse --> DISCARD (git reset)
6. LOG      -- append to .godmode/<skill>-results.tsv
7. REPEAT   -- until goal met or iteration budget exhausted

No human approval needed between iterations. Every experiment is committed to git. Every discard is classified and remembered.

The Full Pipeline

THINK --> PLAN --> BUILD --> TEST --> FIX --> OPTIMIZE --> SECURE --> SHIP

Godmode detects which phase you're in and routes to the right skill. Skills chain automatically — optimize finds an issue, triggers fix, re-optimizes, then ships.

Failure Intelligence

Every discard is classified into one of 8 failure types and logged to .godmode/<skill>-failures.tsv. On 3+ consecutive failures, the agent writes a reflective diagnosis analyzing the pattern before trying again. Lessons persist in .godmode/lessons.md across sessions.

Multi-Agent Execution

Complex tasks are decomposed and run in parallel:

Round 1:  Agent 1 [worktree] --\
          Agent 2 [worktree] ---+-- merge + test
          Agent 3 [worktree] --/
Round 2:  Agent 4 [worktree] --\
          Agent 5 [worktree] ---+-- merge + test

Max 5 agents per round. Each gets its own git worktree. Merge sequentially, test after each merge.

What Fires by Default

Every /godmode:* invocation — and every natural-language request that routes to a pipeline skill — fires the full learning stack automatically. No flags, no opt-in. See SKILL.md §14 Default Activations for the authoritative list.

Authoring discipline (Karpathy family)

• Principles prelude — every agent reads skills/principles/SKILL.md before the first Edit. Four rules: Think Before Coding (state assumptions, surface alternatives), Simplicity First (pre-MODIFY strike for single-use helpers and unrequested configurability), Surgical Changes (line-trace rule), Goal-Driven Execution (success criterion is a shell command exiting zero).
• Pre-commit discard audit — builder, tester, and optimizer agents classify every hunk in git diff --cached before committing. line_scope_drift hunks (formatting churn, "while we're here" refactors, adjacent improvements) are surgically dropped via git restore -p --staged. Spec: docs/discard-audit.md.
• DispatchContext schema — all 7 subagents validate their input at dispatch time. Missing required field → BLOCKED: invalid_dispatch. See AGENTS.md § DispatchContext Schema.
• Discard cost hierarchy — Cost-0 (pre-MODIFY strike) / Cost-1 (pre-commit audit) / Cost-2 (post-commit revert). Cost-2 discards that should have been caught earlier are logged as escaped_discard feedback to .godmode/lessons.md.

Token optimization (four-layer stack)

• Progressive Disclosure routing — the orchestrator reads only Tier 1 of each skill file (~20 lines) to match triggers. ~2,700 lines to route vs ~27,000 for full reads. ~90% routing-time context reduction.
• Stdio input-side compression — skills/stdio/SKILL.md documents 13 canonical command patterns (git log → git log --oneline -20, cat → wc -l, ls -la → ls -1, etc.) every agent prefers. Pairs with rtk for shell-hook level enforcement.
• Terse output-side compression — skills/terse/SKILL.md auto-activates from round 2 onward. Compresses round summaries, status lines, agent reports by 40-60%. TSVs, code, errors, commit messages, and final summary stay verbose. Opt out with /godmode:terse off or GODMODE_TERSE=0.
• Token observability — skills/tokens/SKILL.md logs per-round input/output token counts to .godmode/token-log.tsv using a reproducible chars/4 heuristic. Answers "is my loop getting cheaper or more expensive?" with one awk one-liner. Opt out with GODMODE_TOKENS=0.

Coordination and research

• Named coordination patterns — every plan declares its outermost pattern from docs/coordination-patterns.md: Pipeline, Fan-out/Fan-in, Expert Pool, Producer-Reviewer, Supervisor, or Hierarchical Delegation. Plans without a declared pattern return BLOCKED: invalid_plan.
• Research auto-dispatch — before routing to think on any non-trivial task (mentions external lib/framework, >5 file scope, no prior .godmode/research.md), the orchestrator auto-dispatches skills/research/SKILL.md to gather prior art. Skip for trivial fixes or with --no-research.

The 8 pipeline skills inherit by default

THINK → PLAN → BUILD → TEST → FIX → OPTIMIZE → SECURE → SHIP

Each of these skills has a Rule 0 in its Hard Rules section explicitly inheriting all of the above. No per-skill opt-in. One command runs the whole stack.

Subagents (7)

Skills (135)

Godmode includes 135 skills across 13 domains. Each skill encodes a real engineering workflow — not just instructions, but a complete protocol with verification steps.

The 8 Discipline & Context skills (shipped across Phases 0–E)

Full skill reference: skills/

Platforms

omp: served by the same pi installer — ~/.omp/agent/skills is omp's native user skills dir, confirmed from upstream source (can1357/oh-my-pi @ main, 2026-08-27) and verified against omp v18.0.8 (linux-x64). omp scans one level per skill, so the installed godmode/ wrapper is not auto-discovered — register the collection once in ~/.omp/agent/config.yml:

skills:
  customDirectories:
    - ~/.omp/agent/skills/godmode

With an active omp profile, skills load from ~/.omp/profiles/<name>/agent/skills instead. PREFIX is retained for pi-style forks — see adapters/pi/README.md for the full omp walkthrough. Amp: reads root AGENTS.md and the .agents/skills/ project skills directory natively (docs); the adapter wires godmode's skills there. Subagents and model routing are Amp's own — the adapter wires neither.

All 135 skills work on every platform. Parallel agent skills automatically degrade to sequential on platforms without native agent dispatch. The authoring-discipline prelude, Progressive Disclosure routing, and pre-commit discard audit all reach every adapter — Claude Code via SKILL.md, Gemini and OpenCode via their respective entry files importing @./skills/principles/SKILL.md.

Verify your installation: bash adapters/<platform>/verify.sh (pi family: point it at your skills dir, e.g. PREFIX=<dir> bash adapters/pi/verify.sh for an omp install)

Multi-model routing

Zero config is a valid, complete default: with no configuration at all, every role inherits the session model, and godmode works fully with zero setup. A missing godmode.models.json is a valid state, and model tiering is opt-in only. When a role is pinned, resolution is exactly one chain:

GODMODE_MODEL_<ROLE> env -> godmode.models.json roles -> session model.

The repo-root godmode.models.json wins per key over ~/.config/godmode/models.json when both exist: a role pinned in the repo file wins, while roles set only in the user file still apply.

A one-off override is an env var per role — role name uppercased, dashes to underscores (code-review -> GODMODE_MODEL_CODE_REVIEW):

GODMODE_MODEL_EXECUTE=zai/glm-5.3-flash GODMODE_MODEL_PLAN=anthropic/claude-opus-4 godmode optimize

Durable config lives in godmode.models.json — at your project root (commit it to share team-wide routing) or in ~/.config/godmode/models.json (personal, machine-wide). Mix providers freely:

{
  "roles": {
    "plan": "anthropic/claude-opus-4",
    "review": "anthropic/claude-opus-4",
    "build": "openai/gpt-5.2",
    "optimize": "zai/glm-5.3-flash"
  }
}

Illustrative example: a 20-round optimize loop can run fast/cheap executors under strong reviewer models — spend shifts toward the rounds that benefit instead of paying premium prices for every round. Actual savings depend on your providers and pricing.

Capability tiers — which harnesses accept per-child model params:

Inspect what will run before you start: godmode doctor (/godmode:doctor) prints the resolved role -> model table with each value's source (env / file / session).

Roles are open-ended — there is no fixed enum — and any unknown or unpinned role simply falls back to the session model. Details and the full reference resolver: adapters/pi/README.md.

Philosophy

Discipline before speed. Every change is measured. Bad changes are reverted.

Evidence before claims. "Looks good" is rejected. Numeric proof is required.

Git is memory. Every experiment is committed. Every revert is in the log.

Keep or discard. Binary decisions only. No maybes.

Learn from failure. Every discard is classified and remembered.

Simplicity first. Complex changes that marginally improve metrics are discarded. The pre-MODIFY checklist strikes speculative code before it's written.

Think before coding. If two interpretations exist, present them — never silently pick. Emit NEEDS_CONTEXT on ambiguity.

Surgical changes only. Every semantically changed line must trace directly to the user's request. Adjacent "improvements" are line_scope_drift — dropped at pre-commit audit.

Goal-driven execution. Success is a shell command that exits zero. Subjective criteria ("works well," "looks good," "is faster") are vibes — reject them before coding.

Token budget is a first-class metric. Input-side (stdio), routing (Progressive Disclosure), output-side (terse), and observability (tokens) stack multiplicatively. Every round logs its context cost.

Contributing

Every skill is a Markdown file. If you can write clear instructions, you can add a skill.

See CONTRIBUTING.md for the complete guide:

• Adding a New Skill
• Skill Quality Checklist
• Adding a New Platform Adapter
• Testing Your Changes
• Style Guide

Frequently Asked Questions

Community

Wins, questions, and failure stories are welcome in Discussions. Share what godmode kept — or reverted — for you.

License

MIT -- see LICENSE.