Troubleshooting

"ArmorCodex intent plan missing for this session"

Cause: Codex did not call register_intent_plan before using a tool. This happens when the plan expired or the session just started.

Fix: Re-prompt. Codex will register a new plan.

"ArmorIQ intent token expired"

Cause: The token TTL (default 5 minutes) expired before Codex finished executing. Complex prompts with long thinking times can exceed this.

Fix:

export ARMORCODEX_VALIDITY_SECONDS=600

This sets the TTL to 10 minutes.

"ArmorCodex intent drift: tool not in plan"

Cause: Codex tried to use a tool it did not declare in its plan.

Fix: This is working correctly. Intent drift detection is blocking an unplanned tool. Codex should re-register a plan that includes the tool, which it usually does automatically on retry.

MCP "Transport closed" error during register_intent_plan

Cause: The ArmorIQ SDK round-trip exceeded Codex's ~1 second MCP transport timeout. The local plan is still stored, but the signed token isn't issued in time.

Fix: The installer bakes ARMORCODEX_USE_SDK_INTENT=false into the MCP env block by default for exactly this reason. Plans are stored locally and PreToolUse uses them; the SDK call happens in the background via the audit path. To re-enable signed tokens at the cost of occasional transport timeouts:

unset ARMORCODEX_USE_SDK_INTENT
export ARMORCODEX_INTENT_DEADLINE_MS=500   # hard cap on SDK round-trip

"Policy denied path /steps/[0]/tool"

Cause: The backend's OPA policy is denying tool calls at token issuance time. This happens when your ArmorIQ tenant has blocking policies with no allow-rules.

Fix:

export CSRG_VERIFY_ENABLED=false

Or configure allow-rules in your ArmorIQ tenant dashboard.

Hook errors on session start

Cause: Plugin dependencies corrupted or partially installed.

Fix:

cd ~/.armoriq/armorCodex/plugins/armorcodex
rm -rf node_modules
npm install --omit=dev

Then restart your Codex session.

Marketplace tab shows ArmorCodex but Plugins tab doesn't

Cause: Codex Desktop's Plugins panel only shows installed plugins. Codex 0.128's CLI doesn't yet expose codex plugin install, so the desktop UI is the only path to flip a discovered plugin to "installed".

Fix: Open Codex Desktop, go to Plugins, find ArmorCodex's tile, and click the Install button. Restart the app if the panel doesn't refresh after install.

Plugins panel still empty after marketplace add

Cause: Stale marketplace clone or cached plugin discovery state.

Fix:

codex plugin marketplace remove armorcodex
codex plugin marketplace add armoriq/armorCodex

Then quit and reopen Codex Desktop completely (Cmd+Q on macOS, not just close the window).

"Plugin not found in marketplace" on install

Cause: The armoriq/armorCodex GitHub repo is private or your machine does not have access.

Fix: Either make the repo public (recommended for open distribution) or authenticate with gh auth login using an account with org access.

Policy commands do not show feedback

Cause: UserPromptSubmit hook results may not always surface visually on the first try.

Fix: The policy IS being set correctly (test with Show me the current ArmorCodex security policies). If the first response does not show confirmation, the rule is still active.

"armoriq: command not found" after install

Cause: Global npm install failed (permissions issue), and the installer's Python SDK fallback isn't on your PATH either.

Fix:

npx @armoriq/sdk-dev login --product armorcodex

Or fix npm permissions and reinstall:

sudo npm install -g @armoriq/sdk-dev

Or install the Python SDK with --product support:

pip install -U armoriq-sdk-dev
armoriq login --product armorcodex

Browser approval shows generic ArmorIQ branding instead of ArmorCodex

Cause: Either the SDK CLI you're using doesn't support the --product flag (older @armoriq/sdk-dev on npm) or the production backend / frontend has not yet picked up the product-aware-device-flow changes.

Fix: Make sure the Python SDK is at 0.3.6+ (pip install -U armoriq-sdk-dev then armoriq login --product armorcodex). For the backend / frontend side, the changes ship via conmap-auto + armorIQ-Frontend dev → main promotions. Until those are in prod, the SDK still appends &product=armorcodex to the URL client-side, but the frontend may not yet render the product-aware heading.

Debug Mode

To see what ArmorCodex is doing:

export ARMORCODEX_DEBUG=true
codex

Debug output goes to stderr. You will see hook events, plan registration details, policy evaluation results, and backend API calls.