arbazkhan971/godmode

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.

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.

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.

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

---

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/-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/-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//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//verify.sh (pi family: point it at your skills dir, e.g. PREFIX= 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_ 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.

---