Troubleshooting

"ArmorClaude intent plan missing for this session"

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

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

"ArmorIQ intent token expired"

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

Fix:

export ARMORCOWORK_VALIDITY_SECONDS=600

This sets the TTL to 10 minutes.

"ArmorClaude intent drift: tool not in plan"

Cause: Claude 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. Claude should re-register a plan that includes the tool, which it usually does automatically on retry.

"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 ~/.claude/plugins/marketplaces/armoriq
rm -rf node_modules
npm install --omit=dev

Then restart Claude Code.

"Plugin not found in marketplace" on install

Cause: The armoriq/armorClaude GitHub repo is private and 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: In Claude Desktop, the UserPromptSubmit hook results may not always surface visually on the first try.

Fix: The policy IS being set correctly (test with Policy list). If the first response does not show confirmation, the rule is still active.

Token says "Token valid 60s" but expires too fast

Cause: Older version of ArmorClaude with 60-second default TTL.

Fix: Update the plugin:

claude plugin update armorclaude

The latest version defaults to 300 seconds (5 minutes).

Plugin works in CLI but not Desktop

Cause: Desktop may have a cached older version of plugin files.

Fix: Restart Claude Desktop completely (Cmd+Q on macOS, not just close the window), then reopen.

"armoriq: command not found" after install

Cause: Global npm install failed (permissions issue).

Fix:

npx @armoriq/sdk-dev login

Or fix permissions:

sudo npm install -g @armoriq/sdk-dev

Debug Mode

To see what ArmorClaude is doing:

export ARMORCOWORK_DEBUG=true
claude

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