optimus

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 to keep them accurate.

Optimus works alongside the hosts' built-in tools. In Claude Code, use Anthropic's official code-review plugin for post-push PR review and /simplify for per-change cleanup; refactor restructures against your project guidelines. Native goals in Claude Code and Codex continue across turns toward a completion condition, subject to host permissions and stopping rules. gauntlet can export its builder/critic protocol for either host's goal mechanism; deep provides the deterministic resumable fix loop with test bisection and checkpoints.

Skills

Open a skill's documentation for examples, options, and prerequisites. Run init before using the quality skills; tdd needs working tests, and deep needs a configured test command.

Core

Skill	Use it to…
/optimus:init	Set up project guidance and test infrastructure, scaffold an empty project, or refresh an existing setup.
/optimus:brainstorm	Explore design options and write a spec for implementation; use scaffold for a new product's planning docs.
/optimus:jira	Turn a Jira issue into a task with acceptance criteria and codebase context. Requires a compatible Jira MCP server.
/optimus:tdd	Implement a task or spec through Red-Green-Refactor cycles, with commits per behavior and a final push.
/optimus:unit-test	Find coverage gaps and add tests that follow project conventions, without refactoring source code.
/optimus:refactor	Improve code against project guidelines, with optional testability or guidelines focus.
/optimus:code-review	Review local changes or a PR/MR for bugs, security issues, and guideline compliance.
/optimus:deep	Repeat review, refactoring, or coverage passes with fixes, tests, and progress you can resume across sessions.
/optimus:paper-init	Prepare a paper's sources, implementation spec, and evidence-based reproduction criteria before writing code.
/optimus:gauntlet	Pursue an ambitious goal through builder/critic iterations against a concrete quality bar, until it passes or you stop.

Utility

Skill	Use it to…
/optimus:commit	Stage and commit with an optional push; use suggest for a message only or branch to move local changes to a new branch.
/optimus:pr	Create or update a GitHub PR or GitLab MR with intent, scope, and a test plan.
/optimus:worktree	Create an isolated Git worktree with project setup and a test baseline.
/optimus:handoff	Save enough context for a fresh agent to resume the work.
/optimus:how-to-run	Generate or refresh a HOW-TO-RUN.md for local setup and development.
/optimus:permissions	Claude Code only: configure branch protection, file safeguards, and routine tool permissions.
/optimus:prompt	Turn an idea into a copy-ready prompt for an AI tool.
/optimus:reset	Remove selected Optimus project artifacts; use permissions to remove only the permissions setup while keeping init. Preserves tests and does not uninstall the plugin.
/optimus:dream	Claude Code only: review and consolidate stale auto-memory, with confirmation before deletion.

Recommended Workflow

1. Set up: run init. In Claude Code, optionally run permissions first; in Codex, configure its sandbox and approval policy.
2. Build: use tdd "description" for a clear task, brainstorm when design decisions are needed, or jira PROJ-123 for tracked work.
3. Improve: use unit-test to fill coverage gaps and refactor to improve existing code.
4. Ship: run commit → pr in the implementation conversation, then code-review in a fresh conversation. This carries the reasons for the change into the review. tdd already commits and pushes, so follow it with pr → review.

For longer work, deep review, deep refactor, and deep coverage repeat those passes automatically. Codex orchestration remains experimental; check its support limits before unattended use.

Maintenance: re-run init after major changes, use how-to-run for setup guidance, and reset to remove generated project files. The reset documentation also covers uninstalling the plugin.

Using with OpenAI Codex

Claude Code is the primary host. Codex support is experimental: shared skills use the same project guidance, but some host features are unavailable. Follow the Codex Quick Start to install and initialize.

Supported hosts and versions

These are recorded checks as of 2026-09-09, not minimum required versions or proof that every workflow works. Use a release of your host that supports plugins; see Claude Code and Codex plugin availability.

Host	Validation status
Claude Code, native Windows CLI	Primary host. 2.1.263 and 2.1.266 loaded the plugin; 2.1.266 passed commit suggest and Python init smoke checks on the 3.12.0 candidate.
Codex, native Windows CLI/app-server	Experimental. 0.153.4 passed installation, skill discovery, and launcher checks through plugin 3.12.1; this does not validate all skill workflows.
Codex desktop	Full skill workflows and updates remain unverified.
macOS/Linux CLI, including WSL	Not exercised in the recorded audit.
Codex IDE extension	Plugins are not supported in this surface.
Remote/cloud sessions	Not exercised in the recorded audit.

Validation procedures and remaining checks are in CONTRIBUTING.md.

Support matrix

All Codex workflows remain experimental. Portable means no known host-specific dependency in the core instructions, not a completed end-to-end test. Agent execution and available parallelism still need verification.

Skill or feature	Codex status and limits
commit, pr, handoff, worktree, how-to-run, paper-init, code-review, refactor, unit-test, tdd, reset	Portable. Follow each skill's setup, tool, and test prerequisites.
init	Partial: creates shared docs, tests, and AGENTS.md pointers; preserves existing hooks/settings and skips formatter installation.
brainstorm, jira, prompt	Partial: Claude plan-mode handoffs need manual adaptation. Jira needs a compatible MCP server configured in Codex; bundled setup is Claude-only.
deep	Experimental orchestration: multiple iterations, nested agents, resume, and headless execution need further testing.
gauntlet	Experimental orchestration: in-session execution and Copy as /goal prompt for a new Codex session. The handoff uses native Codex goals when available, with a plain-prompt fallback; full builder/critic execution remains unverified. Claude's /effort → ultracode prerequisite does not apply.
permissions, dream	Unsupported. Use Codex's own sandbox, approval policy, and memory controls.
Formatter hooks	Unsupported. Use editor formatting or pre-commit hooks.
Standalone code-simplifier / test-guardian plugin agents	Unsupported. Use the refactor / unit-test workflows.