A Claude Code plugin that sets up your project for effective AI-assisted engineering.
The problem: AI amplifies whatever it finds. Messy code leads to messier AI-generated code, which becomes the new context for even worse output — a vicious cycle that compounds faster than any human could create technical debt. Without maintained context, any AI coding tool's quality degrades with every file it reads.
The solution: Optimus Claude generates tailored CLAUDE.md files, coding guidelines, formatter hooks, and test infrastructure from your actual codebase, then enforces those standards in every quality pass — code review, refactoring, TDD, and a resumable deep-fix loop. Use it regularly and your project stays clean, consistent, tested, and well-documented: exactly the conditions where Claude Code performs at its prime.
The philosophy: It's all about perfecting context. The codebase, prompts, unit tests, docs, commit messages, PR descriptions — it all adds up to shape how well Claude Code performs. Every skill is lean by design: 3.0 cut the plugin's own instruction footprint by more than half so the skills spend your context window on your project, not on themselves.
Quick Start
Run these commands inside Claude Code:
/plugin marketplace add https://github.com/oprogramadorreal/optimus-claude.git
/plugin install optimus@optimus-claude
Then start a new session and type /optimus:init in any project directory. Having trouble? See Troubleshooting.
How It Works
/optimus:init analyzes your codebase and generates constraint docs — coding guidelines, CLAUDE.md, formatter hooks, and test infrastructure — into your .claude/ directory, detecting your stacks (Python, Node, Rust, UI frameworks, and more). It also recognizes skill authoring as a stack: if your project's "source code" includes markdown instructions authored for an AI agent (a Claude Code plugin, a prompt library), init installs skill-writing-guidelines.md, and the review/refactor skills route markdown instruction files through that lens while code files go through coding-guidelines.md.
From then on, the quality skills enforce your standards, not generic ones: /optimus:code-review checks your naming conventions and architectural patterns alongside bugs and security; /optimus:tdd applies your guidelines during the Refactor step; /optimus:refactor uses them as its quality lens; /optimus:unit-test follows your testing conventions. /optimus:deep sustains any of those passes across iterations — a fresh subagent per pass, tests and deterministic bisection between passes, resumable on-disk state.
Design principles: skills never auto-trigger (the only always-on component is a lightweight read-only SessionStart hook that surfaces project state), and generated output is project-scoped — guidelines and hooks travel with the repo via git and work for every teammate without the plugin.
Skills
Core
| Skill | Description |
|---|
/optimus:init | Initializes project documentation, formatter hooks, and test infrastructure from your actual codebase. Offers new-project scaffolding on empty directories; audits and syncs on re-run. |
/optimus:brainstorm | Structured design brainstorming — explores the codebase, proposes approaches with trade-offs, writes an approved spec to docs/specs/ that /optimus:tdd consumes. scaffold mode stamps an empty docs-first steering cascade (product vision, MVP PRD, tech stack) for a human to fill. |
/optimus:jira | Fetches a JIRA issue via MCP and distills it into a structured task at docs/jira/ that downstream skills auto-detect. Analyzes the codebase for missing criteria and risks; recommends the next skill by complexity. |
/optimus:tdd | Test-driven development through Red-Green-Refactor cycles with per-behavior commits and branch push. Auto-detects specs from docs/specs/ or docs/jira/. Requires init. |
/optimus:unit-test | Discovers coverage gaps and writes convention-following tests. Never refactors source code; stops with a triage pointer when the test baseline is broken. Requires init. |
/optimus:refactor | Refactors for guideline compliance and testability through four analysis lenses, with testability and guidelines focus modes. Run init first. |
/optimus:code-review | Reviews changes for bugs, security issues, and guideline compliance through 5 to 7 review lenses. Auto-routes to PR mode on a clean branch with an open PR/MR and reads the PR description as author intent. |
Utility
| Skill | Description |
|---|
/optimus:commit | Stages, commits, and optionally pushes with a conventional commit message; captures the "why" from the implementation conversation. suggest mode is read-only; branch mode moves local changes to a conventionally named branch without committing. |
/optimus:pr | Creates or updates a PR/MR with a structured description — intent, scope, non-goals, test plan — that /optimus:code-review consumes. Supports GitHub and GitLab. |
/optimus:worktree | Creates an isolated git worktree for parallel development, running project setup and a test baseline automatically. |
/optimus:handoff | Compacts the current conversation into a self-contained, redacted handoff doc under docs/handoffs/ so any fresh agent can resume the work. |
/optimus:how-to-run | Generates a HOW-TO-RUN.md that teaches a new developer how to set up and run the project locally; audits it against actual project state on re-run. |
/optimus:permissions | Configures branch protection, precious-file safety, and auto-approved routine tool calls via allow/deny rules and a PreToolUse hook. |
/optimus:prompt | Crafts optimized, copy-ready prompts for any AI tool — extracts intent, selects a template, audits for token efficiency. |
/optimus:reset | Removes files installed by init and permissions. Classifies each file before deletion and always asks for confirmation. |
Recommended Workflow
- Setup —
/optimus:permissions for guardrails, then /optimus:init to generate project context and test infrastructure.
- Strengthen —
/optimus:unit-test for coverage (or /optimus:deep coverage for the automated loop), /optimus:refactor for code quality.
- Build — pick the entry point that matches the task:
/optimus:tdd "description" directly for small clear work; /optimus:jira PROJ-123 first for tracked work; /optimus:brainstorm first when design decisions are needed (greenfield products start with /optimus:brainstorm scaffold); /optimus:gauntlet <goal> for ambitious long-horizon goals judged against a concrete quality bar.
- Ship —
/optimus:commit → /optimus:pr → /optimus:code-review in a fresh conversation (or /optimus:deep review for iterative auto-fix).
Keep intent flowing from implementation to review: stay in the implementation conversation when running /optimus:commit and /optimus:pr — they capture why the change was made into the commit message and PR description. Then review in a fresh conversation: /optimus:code-review reads the PR description as author intent and checks whether the implementation delivers what it claims, not just whether it follows style rules. (/optimus:tdd auto-commits per cycle and pushes at the end, so its flow collapses to tdd → pr → review.)
After major changes — re-run /optimus:init to audit and refresh the generated docs. New to a codebase? — /optimus:how-to-run. Removing optimus — /optimus:reset.
Why It Works
What makes a good developer productive also makes Claude Code productive: clean code, good tests, and clear docs.
Research backs this up: AI tools introduce 30%+ more defects on poorly maintained code, and LLM performance degrades up to 85% as context length grows. Clean, DRY code with meaningful names keeps context lean and gives the LLM better semantic signals. The 2025 DORA report puts it simply: AI amplifies existing practices, good or bad.
Another key point: providing LLMs with tests alongside tasks consistently improves code generation. Tests enable self-correction — Anthropic's #1 best practice for Claude Code is giving it a way to verify its work, and unit tests and TDD are the purest way to achieve it.
AI assistants also tend toward sycophancy — validating ideas without critical pushback. This plugin counters that: every skill enforces project-defined standards as the source of truth, quality claims require evidence from actual command output, code review runs independent agents on separate lenses and validates every finding against the code before reporting it, and TDD ensures tests define what is correct instead of relying on the AI's confidence.
Complementary Tools
optimus-claude works alongside official tools, not against them. Use Anthropic's official code-review plugin for post-push PR review, the builtin /simplify for per-change cleanup (complemented by /optimus:refactor for project-wide restructuring), Claude Code's native dynamic workflows for one-off background multi-agent builds and sweeps, and built-in sandboxing for autonomous execution with OS-level isolation.
Claude Code's /goal is complementary to /optimus:deep: reach for /goal for lightweight "work until a condition holds" in a single session; reach for /optimus:deep for the deterministic, resumable fix loop — fresh subagent per iteration, test bisection that reverts the exact fix that broke the build, and on-disk state that survives across sessions.
Troubleshooting
Windows: SSL certificate error during install
If you see SSL certificate OpenSSL verify result: unable to get local issuer certificate when running /plugin marketplace add, Git for Windows is using an outdated OpenSSL CA bundle. Switch to the native Windows certificate store, then retry:
git config --global http.sslBackend schannel
Upgrading from 3.5.0 or earlier
3.5.1 replaced the Python formatter hook .claude/hooks/format-python.py with a portable bash one, format-python.sh, because the Python version needed a python on PATH — which on Windows hits the Store alias stub and fails on every edit.
Re-running /optimus:init performs the swap, including deleting the old file and its settings.json entry. To do it by hand instead: delete .claude/hooks/format-python.py and remove the PostToolUse entry whose command references it. Leaving it in place means two Python hooks fire per edit.
The replacement resolves black and isort from a .venv, venv, or env directory at or above the edited file, then from PATH — so a virtualenv kept outside the project (Poetry's default, pipenv, conda) needs the formatters on PATH instead. The hook prints a one-line notice to stderr when it cannot find them.
Upgrading from 2.x
3.0 consolidated 22 skills into 16 with no functionality loss except /optimus:workflow (Claude Code's native dynamic workflows cover it):
| Removed in 3.0 | Use instead |
|---|
/optimus:code-review-deep | /optimus:deep review |
/optimus:refactor-deep | /optimus:deep refactor |
/optimus:unit-test-deep | /optimus:deep coverage |
/optimus:branch | /optimus:commit branch |
/optimus:commit-message | /optimus:commit suggest |
/optimus:spec-init | /optimus:brainstorm scaffold |
/optimus:workflow | Claude Code's native dynamic workflows |
Headless entry points move accordingly, e.g. claude -p "/optimus:deep review --yes 'src/auth'". Progress files are unchanged and 2.x runs remain resumable — an in-flight 2.x *-deep run can be resumed with the matching /optimus:deep <target> --resume (one scope-semantics upgrade: a free-text 2.x coverage scope is migrated to recorded intent on first resume, since 3.0 only filters on real paths).
Upgrading from 1.x
The two terminal-run Python harnesses were replaced in 2.0 by in-conversation orchestration — now /optimus:deep (see the 2.x table above).
Contributing
See CONTRIBUTING.md for project structure, skill anatomy, feature branch testing, and local development setup.
Acknowledgements
The /optimus:prompt skill's prompt engineering techniques are adapted from prompt-master by @nidhinjs.
The /optimus:gauntlet skill implements the Gauntlet Loop method by Matt Shumer.
Research & References
