codexclaw

English | 한국어 | 中文

codexclaw

Development discipline and multi-model subagents for OpenAI Codex, packaged as a single plugin.

Workflow inspiration: OMO / oh-my-openagent. Some components are adapted from historical MIT-licensed LazyCodex/OMO; credits, pinned sources and modifications. CodexClaw is a separate, unofficial project.

---

codexclaw turns the Codex runtime into a disciplined development environment. It does not ship its own agent harness — it layers skills, hooks, and components directly on codex, adding structured workflows, coding discipline, and multi-model orchestration that the base runtime doesn't provide.

Features

Dev Skill Family — 12 surface-specific routers (dev-architecture, dev-backend, dev-frontend, dev-testing, dev-security, dev-debugging, dev-data, dev-devops, dev-code-reviewer, dev-scaffolding, dev-visualizer, dev-uiux-design) governed by a canonical parent (dev). Every router inherits the parent's rule classes, verification gate, and safety rules. 155 unique rule IDs across the family.

PABCD Workflow — Plan / Audit / Build / Check / Done, implemented as a file-backed FSM with attestation-gated transitions. Phases advance through cxc orchestrate commands; each transition carries structured evidence. A durable goalplan ledger tracks work phases, success criteria, and captured proof across multiple cycles.

IDLE ── P ── A ── B ── C ── D ── IDLE
       │    │    │
      gate  gate gate
       └────┴────┴──── I (Interview, context preserved)

Multi-Model Subagents — role-based dispatch (explorer / reviewer / executor / architect) with per-role model and prompt overrides. Configuration persists across sessions and applies automatically through the spawn-wrapper hook. A local GUI (Vite + React) provides visual config and, when opencodex is detected, a provider link bar. (Dashboard: build from a repo checkout for now; bundled in a follow-up release.)

Architect proposes design and checks main's plan for alignment in each formal P plan; main owns the executable plan and decisions, and the independent reviewer retains A audit. It reuses one context per plan and rechecks only recorded design-decision changes. This is agent-followed guidance, not runtime enforcement. See the planning lifecycle.

Architect follows the live spawn schema. When native agent_type: "architect" is exposed, use it. On V1 without an agent_type field, use CXC-ROLE: architect in the supported message or text item, attach dev and dev-architecture, and state the read-only task constraints. This logical role needs no exception approval or registration; it does not claim a native read-only sandbox. A typed schema missing architect still needs authorized cxc subagents register architect, a fresh session and a live-schema check, without aliasing explorer/reviewer. Registration is never performed by dispatch. Design consultation and independent audit remain separate.

Subagent settings resolve per role: project → global → original session. Open Global Settings to edit user defaults in $CODEXCLAW_HOME/subagents.json (default ~/.codexclaw/subagents.json). The existing Subagents page edits /.codexclaw/subagents.json: each model dropdown offers Main model, Global settings, and individual models. Global settings follows the entire role's defaults, including effort and prompt; choose a main/direct model to customize that project role. Existing explicit project entries and effort: null retain their meaning. Main model changes only the model source; session effort separately inherits the original session's effort.

The shared catalog reads OCX's enabled models with the non-mutating ocx models live --json, refreshes after a short cache lifetime, and supports Refresh models. Disabled or pending models are excluded. If OCX is absent it reads the configured Codex catalog (model_catalog_json, with CODEX_MODELS_CACHE_PATH override). An unavailable source yields an explicit error or labeled last-known list, never a fabricated four-model roster. The dashboard restricts effort choices to the model's advertised supported values; CLI/MCP validation still validates wire values only, not model-specific compatibility.

CLI list/get/set/reset accept trailing --global. MCP subagents_get/subagents_set and GET /api/subagents?scope=global / POST scope: "global" share the same store. inherit: true removes the selected scope's entire role override; effort: null only clears effort. The former unpublished $CODEX_HOME/codexclaw/subagents.json path is read only if the canonical file is absent and CODEXCLAW_HOME is not explicitly set. The first explicit global edit/reset preserves its other roles in the canonical file and leaves the old file untouched.

Recall — searches past Codex conversations and the memory store from disk artifacts before asking the user, so context survives session boundaries and compaction.

Repo Map — cxc map <dir> runs tree-sitter parsing + PageRank ranking to produce a structure overview of unfamiliar code, letting the agent orient before deep rg dives. (Repo checkout only — requires the vendored Python toolchain.)

Skill Search — cxc skill search <query> discovers dormant skills across cli-jaw-skills (primary), ClawHub, and Hermes catalogs. cxc skill show <id> loads them on demand.

Install

2 lines to install. No build step, no npm install, no config edits.

codex plugin marketplace add https://github.com/lidge-jun/codexclaw
codex plugin add codexclaw@codexclaw

Then restart Codex and approve the 31 hooks when prompted (upgrades ask again — content-hash trust). Everything runs from chat, and the terminal surface ships too — the payload includes its own `