Why

A Claude Code plugin built around a deliberate division of labor between two AI coding agents:

Claude implements — planning, coding, subagents, agent teams
Codex reviews — pre-implementation research, plan critique, code review, documentation accuracy review

Thesis: Claude is the builder, Codex is the critic. You get better software with a smarter cost split.

The cycle

        ┌─ refine ─┐            ┌──── fix ───┐            ┌──── fix ───┐
        ▼          │            ▼            │            ▼            │
research → plan → plan-review → implement → code-review → docs-sync → docs-review → ship
   │         │         │            │            │            │            │           │
Codex+Claude  Claude   Codex   Claude(+agents)  Codex      Claude       Codex        user

When the idea itself is vague (not just un-planned), an optional hyper-interview front-end clarifies it into a spec before research / plan — a short one-question-at-a-time interview, Claude-only (no Codex; clarity is its job, review happens downstream).

The refine / fix arcs are exactly what hyper-plan-loop, hyper-implement-loop, and hyper-docs-loop automate — a Claude-side teammate (planner / fixer / documenter) revises while Codex stays the reviewer, looping until no blocking findings remain.

Layers

Commands

Explicitly-invoked slash commands, auto-discovered; no manifest entry required. Currently one: hyper-setup — a local prerequisite doctor that never spawns Codex or agents.

Skills

Codex gates (hyper-research, hyper-plan-review, hyper-code-review, hyper-docs-review) plus Claude orchestrators and autonomous loops. All surface via Claude Code’s description-triggered dispatch.

Agents

Claude implementation arm: planner, implementer, verifier, documenter, researcher, fixer. Sub-Claude personas with restricted tool lists; used by skills, never the other way around.

Hooks

SessionStart reminder — injects a workflow router prompt plus an optional .hyperclaude/ snapshot footer so every session starts context-aware.

Codex gates & the read-only sandbox

Every fresh codex exec invocation (research, plan-review, code-review, docs-review) passes --sandbox read-only. Resumed sessions use -c sandbox_mode=read-only as a config override. In every mode, Codex’s role in hyperclaude is critic, never editor.

Quick start

1. Install the plugin via Claude Code

/plugin marketplace add zeikar/hyperclaude
/plugin install hyperclaude

2. Verify prerequisites with the built-in doctor command

/hyperclaude:hyper-setup

Checks Node 18+, codex-cli ≥ 0.130.0, the codex --search global flag, git, and the optional CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS env var. Report-only; nothing is installed automatically.

3. Run the cycle inside any project

/hyperclaude:hyper-research add OAuth login to the API   # Codex+Claude prior-art / pitfalls
/hyperclaude:hyper-plan                                  # Claude writes .hyperclaude/plans/<slug>.md
/hyperclaude:hyper-plan-review                            # Codex critiques the plan
/hyperclaude:hyper-implement                             # Claude executes the plan task-by-task
/hyperclaude:hyper-code-review                            # Codex reviews the diff (branch vs main)
/hyperclaude:hyper-docs-sync uncommitted                  # Claude updates docs for the change
/hyperclaude:hyper-docs-review                            # Codex accuracy gate on docs

# Or let the autonomous loops self-converge in one gesture:
/hyperclaude:hyper-plan-loop add OAuth login to the API   # plan → Codex review → revise, looped
/hyperclaude:hyper-implement-loop <plan path>             # implement → Codex code-review → fix, looped
/hyperclaude:hyper-docs-loop                              # docs → Codex review → fix, looped (default: docs/)
/hyperclaude:hyper-auto add OAuth login to the API        # plan-loop → implement-loop, end-to-end

Skip any step a small change doesn’t need — only code-review is non-negotiable for behavioral changes.

Status

v1.0 — the design has converged

Dogfooded daily; the core surface (skills, bridge modes, artifact paths, frontmatter keys) is settled. Still pre-adoption, so breaking changes may ride a minor bump for now rather than a major one. The autonomous loops depend on Claude Code’s experimental agent-teams feature — that one corner can shift upstream.