@spellguard/codex-plugin

OpenAI Codex plugin for the Spellguard agent control plane. Runs inside the developer's Codex environment and enforces credential scope, detects git-mutating operations, and emits observations to the Spellguard backend.

This plugin is the Codex equivalent of @spellguard/claude-code-plugin (the Claude Code plugin); both speak the same agent-control protocol defined in docs/reference/credential-socket-protocol.md.

Install

Requires Codex CLI ≥ 0.40 and [features] codex_hooks = true in ~/.codex/config.toml.

# Option A: from the Codex Plugin Marketplace
codex plugin install spellguard

# Option B: from a local clone (development / pre-release)
cd packages/codex-plugin
pnpm install
pnpm run build
codex plugin marketplace add . --plugin --project
codex plugin install spellguard

Setup

In a Codex session:

@spellguard-setup

The skill prints a one-time URL — open it in your browser and complete the GitHub-App authorization there. The plugin writes the credential to ~/.config/spellguard/config.json and you're ready to go.

Restart your Codex session after first-time setup so the SessionStart hook picks up the new credential.

What happens in a session

| Hook | Action | |---|---| | SessionStart | Validates the local credential, installs the git credential helper into ~/.gitconfig, spawns the persistent agent-control daemon. | | PreToolUse (Bash) | On every git push / branch-create / gh pr create: probes the credential's revocation state and emits a Codex permissionDecision: 'deny' if revoked. Also emits a scope-filtered observation to the Spellguard backend. | | PostToolUse (Bash) | On git commit: captures the new SHA + branch + message and emits a commit observation. |

The agent-control daemon runs detached and maintains a WebSocket to the Spellguard broker. It receives push events for credential rotations, revocations, and admin config updates without polling.

Configuration

| File | Purpose | |---|---| | ~/.config/spellguard/config.json | Local credential + agent metadata (mode 0600) | | ~/.config/spellguard/agents/<agentId>.pid | Daemon PID file | | ~/.config/spellguard/agents/<agentId>.log | Daemon log file | | ~/.gitconfig | credential.https://github.com.helper set to the plugin's helper |

Feature flag

Codex's hook system is opt-in. Add to ~/.codex/config.toml:

[features]
codex_hooks = true

Without this flag, SessionStart / PreToolUse / PostToolUse never fire and the plugin is inert.

Differences from @spellguard/claude-code-plugin (Claude Code)

| Feature | Claude Code | Codex | |---|---|---| | Manifest path | .claude-plugin/plugin.json | .codex-plugin/plugin.json | | Hook registration | embedded in plugin.json#hooks | separate hooks/hooks.json file | | Skill invocation | /spellguard-setup slash command | @spellguard-setup | | Credential helper install | CLAUDE_ENV_FILE exports | direct git config --global mutation | | Block decision shape | {decision: 'block', message} | {hookSpecificOutput: {hookEventName, permissionDecision: 'deny', permissionDecisionReason}} | | Framework value reported to plugin-sync | framework: 'claude_code' | framework: 'codex' |

The protocol module, the partysocket client, the credential daemon, and every lib/ utility is structurally identical between the two plugins.

Reference

• Parent PRD: docs/prd-agent-control-plane-github-mvp.md § "Codex Plugin Extension"
• Protocol: docs/reference/credential-socket-protocol.md
• Claude Code plugin (reference): packages/claude-code-plugin/README.md
• Codex plugin docs: https://developers.openai.com/codex/plugins
• Codex hooks docs: https://developers.openai.com/codex/hooks