Skip to content

CLAUDE.md

Latest commit

 

History

History
58 lines (50 loc) · 3.17 KB

CLAUDE.md

File metadata and controls

58 lines (50 loc) · 3.17 KB
Raw

cc-plugin-codex

The Codex plugin lives at plugins/cc-plugin-codex and delegates to the Claude Code CLI.

Repository map

  • .agents/plugins/marketplace.json: Codex marketplace entry.
  • plugins/cc-plugin-codex/.codex-plugin/plugin.json: plugin manifest.
  • plugins/cc-plugin-codex/skills/: user-facing and internal skills.
  • plugins/cc-plugin-codex/scripts/claude-companion.mjs: command dispatcher.
  • plugins/cc-plugin-codex/scripts/lib/: Claude driver, job state, rendering, and git review context.
  • tests/: Node test suite for the surviving plugin.

Verify

npm ci
npm run check-version
npm test

CI also installs the marketplace and plugin with an isolated CODEX_HOME.

Verify both CLIs

Verify plugin/CLI behavior empirically (--help, live runs) against the installed codex and claude versions — don't guess from docs or memory. Platform details change quickly.

Codex plugin platform facts

  • Manifest: .codex-plugin/plugin.json; when present, the hooks field points at the hooks.json file (./hooks/hooks.json), not a directory — directory ref silently fails to load. Current Codex also supports default hooks/hooks.json discovery, but this plugin retains the explicit known-good path.
  • Hook env vars include PLUGIN_ROOT/PLUGIN_DATA and compatibility aliases CLAUDE_PLUGIN_ROOT/CLAUDE_PLUGIN_DATA.
  • No command namespacing: a commands manifest field is ignored. Real routing is skills/<name>/SKILL.md; users explicitly invoke skills with $skill-name or select them through /skills.
  • Codex Stop hooks can continue the loop with { "decision": "block", "reason": "..." } or exit code 2. This plugin's current stop-review hook deliberately remains advisory and exits 0.
  • Non-managed hooks require review and persisted trust. For vetted automation, --dangerously-bypass-hook-trust bypasses that trust check for one invocation.
  • Codex prefers the repo marketplace at .agents/plugins/marketplace.json. Install this plugin from the repo root with codex plugin marketplace add .. Public distribution targets OpenAI's universal Plugins Directory using the .codex-plugin/plugin.json manifest.

claude CLI facts relevant to driving it programmatically

  • -p --output-format stream-json requires --verbose or errors outright.
  • --bg is mutually exclusive with -p (separate code path); --bg prompt can be piped via stdin.
  • claude agents --json lists background sessions — records have both a short id and a full-UUID sessionId (the short id is a prefix); don't conflate them when matching.
  • Claude's on-demand background supervisor exposes agents, attach, logs, stop, and daemon. This plugin currently integrates agents and stop; stored background results still point users to the Claude session instead of importing terminal logs.
  • claude auth status --json exits 0 when authenticated and nonzero when not.
  • claude --effort low|medium|high|xhigh|max is real and independent of --model.

Windows gotchas

  • Do not pass Claude arguments through cmd.exe. The driver resolves the native executable or npm entrypoint and keeps shell:false.
  • Route multi-line prompts via stdin on Windows.