Troubleshooting

"ArmorGemini intent plan missing for this session"

Cause: Gemini did not call register_intent_plan before using a tool. This happens when the plan expired, the session just started, or the model ignored the BeforeAgent directive on this turn.

Fix: Re-prompt. The BeforeAgent hook re-injects the directive on every turn, so Gemini registers a new plan on the next try. If it keeps happening, check that the armorgemini-policy MCP server is running (see below).

"ArmorGemini plan expired"

Cause: The registered plan is older than ARMORGEMINI_PLAN_TTL_SECONDS (default 600s). Most prompts finish well within this window, but very long multi-step plans with extended thinking can hit it.

Fix: Re-prompt. BeforeAgent fires again and Gemini registers a fresh plan. To raise the TTL for long-running workflows:

export ARMORGEMINI_PLAN_TTL_SECONDS=1800     # 30 minutes

"ArmorGemini intent drift: tool not in plan"

Cause: Gemini 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. Gemini should re-register a plan that includes the tool, which it usually does automatically on retry. If a legitimate tool is being blocked repeatedly, consider disabling intent enforcement for the session:

export ARMORGEMINI_INTENT_REQUIRED=false     # policy-only mode

Every tool call is denied with "ArmorGemini not configured"

Cause: The plugin cannot find an ArmorIQ API key. It fails closed by design.

Fix:

armoriq whoami

If that reports "not logged in":

armoriq login --product armorgemini

Or set the env var directly:

export ARMORIQ_API_KEY=ak_live_...

The armorgemini-policy MCP server never launches

Cause 1: gemini-extension.json at the plugin root does not list the server. Some installer flows may miss it on upgrades.

Fix: Confirm the manifest:

cat ~/.armoriq/armorGemini/gemini-extension.json

Expect an mcpServers.armorgemini-policy entry that points to ${extensionPath}/scripts/policy-mcp.mjs. If missing, re-run the installer:

curl -fsSL https://armoriq.ai/install_armorgemini.sh | bash

Cause 2: The MCP entrypoint is missing or the Node dependencies are not installed.

Fix:

ls ~/.armoriq/armorGemini/scripts/policy-mcp.mjs
ls ~/.armoriq/armorGemini/node_modules/@modelcontextprotocol/sdk

If either is missing:

cd ~/.armoriq/armorGemini && npm install

Cause 3: The register_intent_plan tool is being blocked by the plugin's own BeforeTool. This should not happen on v0.3.1+ (Gemini-namespaced MCP tools are recognized in the allowlist), but verify the version:

grep version ~/.armoriq/armorGemini/package.json
# expect: "version": "0.3.2" or newer

Backend calls are failing with 401 or 403

Cause: The API key is missing, invalid, expired, or the SDK is reading it from a different location than you set.

Fix:

armoriq whoami

If it reports the wrong account, clear credentials and re-login:

armoriq logout
armoriq login --product armorgemini

Note: 401 and 403 from the backend are treated as fatal and cause the tool call to be denied. 400 responses (bad payload) and network errors fall through to monitor-mode allow so a broken backend does not brick your CLI. See Core Concepts for the full matrix.

/armor:yes does not activate a policy

Cause 1: No pending proposal is staged.

Fix: Stage first with /armor:add ... or /armor:template .... /armor:yes only confirms a pending proposal; it does not create one.

Cause 2: The pending proposal is older than 30 minutes.

Fix: Re-stage with /armor:add ... (the TTL resets on each new stage) and immediately run /armor:yes.

Cause 3: The plugin cannot write to $dataDir.

Fix: Check permissions on ~/.gemini/armorgemini/ (or wherever ARMORGEMINI_DATA_DIR points). The directory must be writable by the user running gemini.

Hooks do not fire on gemini start

Cause 1: The hook block is missing from ~/.gemini/settings.json.

Fix: Re-run the installer:

curl -fsSL https://armoriq.ai/install_armorgemini.sh | bash

Cause 2: The command: path points to a non-existent hook-router.mjs.

Fix: Confirm the ArmorGemini checkout exists at the path referenced in the hooks:

grep armorGemini ~/.gemini/settings.json
ls -la ~/.armoriq/armorGemini/scripts/hook-router.mjs

If the checkout is gone, re-clone it:

git clone https://github.com/armoriq/armorGemini ~/.armoriq/armorGemini
cd ~/.armoriq/armorGemini && npm install

Cause 3: Gemini CLI is caching an older settings.json. Some Gemini CLI builds do not reload settings mid-session.

Fix: Fully quit gemini and reopen. If that fails, run gemini --config-path to confirm which settings file is actually being read.

/armor:* commands do nothing

Cause: TOML files were not copied into ~/.gemini/commands/armor/.

Fix:

ls ~/.gemini/commands/armor/
# expect: add.toml, help.toml, list.toml, no.toml, template.toml, yes.toml

If any are missing, re-run the installer, or copy them from ~/.armoriq/armorGemini/.gemini/commands/armor/.

armoriq: command not found after install

Cause: Global npm install failed (permissions issue).

Fix:

npx @armoriq/sdk login --product armorgemini

Or fix permissions:

sudo npm install -g @armoriq/sdk

Debug Mode

To see what ArmorGemini is doing:

export ARMORGEMINI_DEBUG=true
gemini

Debug output goes to stderr. You will see hook events, plan registration on the MCP server, layered BeforeTool decisions (drift, local policy, backend), and audit calls.