optimus-claude

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 and optimized CLAUDE.md files, coding guidelines, formatter hooks, TDD and test coverage, all based on your actual codebase. Built-in quality agents (code simplifier, test guardian) run alongside every review and refactor.

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: This is all about perfecting context. The codebase, prompts, unit tests, docs, commit messages, PR descriptions, branch names — it's all context and it all adds up to shape how well Claude Code performs. Optimus Claude provides developers ways to create and maintain optimal context for AI-assisted engineering across the entire development workflow.

Quick Start

Install

Run these commands inside Claude Code:

/plugin marketplace add https://github.com/oprogramadorreal/optimus-claude.git
/plugin install optimus@optimus-claude

Having trouble? See Troubleshooting.

Run

Start a new Claude Code session and type /optimus:init in any project directory. See Skills for the full list.

How It Works

Every skill operates on the same shared foundation: your project's coding guidelines and a verification protocol that demands evidence over confidence.

/optimus:init analyzes your codebase and generates constraint docs — coding guidelines, CLAUDE.md, formatter hooks, and test infrastructure (framework, coverage tooling, testing docs) — into your .claude/ directory. The plugin bundles quality agents at two levels: plugin-level agents (code-simplifier, test-guardian) that define reusable quality concerns, and skill-level agents that adapt them for specific workflows within skills like code-review, refactor, and tdd. Skill-level agents often extend the plugin-level definitions with skill-specific scope and output format — see references/agent-architecture.md for the full architecture. From that point on, every optimus skill loads those guidelines, and skills that make completion claims apply the verification protocol as a gate before reporting.

/optimus:code-review doesn't run a generic review — its agents check your naming conventions, your architectural patterns, and your DRY principles alongside bugs and security. /optimus:tdd applies them during the Refactor step. /optimus:refactor uses them as its quality lens. /optimus:unit-test follows them for test naming and structure.

Every skill is also conservative by default — /optimus:unit-test never refactors source code, /optimus:verify runs in an isolated sandbox and never pushes to remote, and /optimus:commit warns about secret files before proceeding.

The result: consistent patterns, meaningful names, and lean context across every operation — exactly the signals that keep Claude Code accurate and productive.

Design Principles

Explicit invocation — Skills never auto-trigger. Claude Code's default behavior is never altered unless you explicitly call a /optimus skill.

Project-scoped output — Formatter hooks and coding guidelines are installed into .claude/ and travel with the repo via git — self-contained and working for every teammate without the plugin. The plugin layers development skills on top: TDD, code-review, commit, refactor, and more.

Skills

Core