Optimus Claude

A plugin that sets up your project for effective AI-assisted engineering in Claude Code, with experimental OpenAI Codex support.

The problem: AI amplifies whatever it finds. Messy code leads to messier AI-generated code, which becomes the context for even worse output, a cycle that compounds faster than any human could create technical debt.

The solution: Optimus generates project instructions, coding guidelines, and test infrastructure from your actual codebase, then holds every quality pass to those standards: code review, refactoring, TDD, and a resumable deep-fix loop. Used regularly, your project stays clean, consistent, tested, and documented: the context your coding agent needs to work well.

The philosophy: It's all about perfecting context. The codebase, prompts, tests, docs, commit messages, and PR descriptions all add up to shape how well your coding agent 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

You need Git for installation and Bash to run the plugin. On native Windows, install Git for Windows first.

Claude Code

Run these commands inside Claude Code:

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

Start a new session in your project directory and run /optimus:init.

OpenAI Codex (experimental)

Use a plugin-capable Codex CLI. From a terminal:

codex plugin marketplace add oprogramadorreal/optimus-claude
codex plugin add optimus@optimus-claude

In Codex, open /hooks to review and trust the session-start hook, then start a new session in your project directory and run $optimus:init. Installation alone does not trust hooks. If the agent has no [optimus] Running under Codex session context, follow Troubleshooting.

Command notation: examples below use /optimus:<skill> for Claude Code. In Codex, use $optimus:<skill> with the same arguments for supported workflows. permissions, dream, and formatter installation are Claude-only; see the Codex support matrix for other limits.

How It Works

init reads your codebase and sets up:

• Project guidance: conventions, constraints, and CLAUDE.md instructions under .claude/, with package-specific guidance in monorepos.
• Test infrastructure: commands and conventions that the testing and review skills use to verify changes.
• Host integration: optional formatter hooks in Claude Code, or AGENTS.md pointers to the shared guidance in Codex.

Skills never run on their own; you invoke them. Generated project docs travel with your repository and remain useful without the plugin. Re-run init after major project changes or to reassess accumulated instructions: it proposes focused edits or a reviewed rebuild of named files while preserving project knowledge by default.