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.

Optimus works alongside the hosts' built-in tools. In Claude Code, use Anthropic's official code-review plugin for post-push PR review, /simplify for per-change cleanup, and /doctor prompt-audit to audit skills, rules, and user-level instructions that init does not manage; 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

Utility

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 init and permissions setup. 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.

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.

If you use AGENTS.override.md, add the project-guidance pointer there yourself: it takes precedence over AGENTS.md, and Optimus manages only AGENTS.md.

Headless runs

After installation, hook trust, project trust, and initialization, this is an experimental Bash/PowerShell example:

codex exec --model gpt-6-astra --sandbox workspace-write '$optimus:deep review --yes'

Preconfigure filesystem, Git, network, and subagent permissions: headless runs cannot obtain fresh interactive approvals. --yes answers Optimus confirmations only. Deep uses Git snapshots and checkpoint commits; --no-commit disables checkpoints but still requires snapshots. See Codex non-interactive execution.

On Windows, complete sandbox setup too; hook trust does not configure it. Where available, --approve-for-me enables automatic permission review in place of --sandbox workspace-write; the flags cannot be combined. Verify effective permissions before a long run.

Troubleshooting

Codex: skills or compatibility context missing

Check that optimus is installed and enabled in /plugins, trust its session-start hook in /hooks, and start a fresh session. Hook changes in an update can require renewed trust. Use $optimus:<skill> mentions.

Bash must be available. On Windows, use Git for Windows or point CLAUDE_CODE_GIT_BASH_PATH at a native bash.exe. Avoid $ or backticks in the plugin installation path; spaces are supported.

Windows: SSL certificate error during install

If /plugin marketplace add reports unable to get local issuer certificate, switch Git for Windows to the native Windows certificate store, then retry:

git config --global http.sslBackend schannel

Contributing

See CONTRIBUTING.md for development setup, testing, and feature-branch installation.

Acknowledgements

• /optimus:prompt adapts prompt engineering techniques from prompt-master by @nidhinjs.
• /optimus:gauntlet implements the Gauntlet Loop method by Matt Shumer.