optimus

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 quality guidelines (coding guidelines for code, skill-writing guidelines for markdown instruction projects) 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. It detects your project's stacks (Python, Node, Rust, UI frameworks, etc.) and installs the matching quality doc for each. This includes skill authoring as a recognized stack: if your project is a Claude Code plugin, a Codex skill repo, a prompt library, or any other project whose "source code" includes markdown instructions authored for an AI agent, init installs skill-writing-guidelines.md alongside coding-guidelines.md, and review/refactor skills route markdown instruction files through the skill-writing lens while routing code files through the coding lens. 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, skills that analyze or modify code load the relevant 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. For projects with a skill-authoring stack, it also reviews markdown instruction files against your skill-writing conventions (progressive disclosure, writing style, reference-depth limits). /optimus:tdd applies coding-guidelines.md 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, 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.