custodex

Universal AI agent governance — one command to govern Claude, Cursor, Gemini CLI, and OpenCode.

npx custodex

What it does

Custodex adds a governance layer to your AI coding tools. Every tool call — file writes, shell commands, MCP actions — is verified against your policies before execution.

npx custodex

  CUSTODEX — Universal AI Governance
  v1.0.0

  Enter your Custodex API key.
  API key: cus_████████████████████████

  Validating API key... OK

  Detecting AI coding tools

  ✓  Claude Code (1.0.23)
  ✓  Cursor
  ✓  Gemini CLI (0.1.8)
     OpenCode — not found

  Install Custodex governance into 3 tools?
  Proceed with installation? [Y/n]: y

  Writing shared config... OK
  Claude Code... OK
  Cursor... OK
  Gemini CLI... OK
  Registering admin agent... OK

  Custodex is now active.  3/3 tools governed.

Supported tools

| Tool | Detection | Governance | |------|-----------|------------| | Claude Code | ~/.claude/ or which claude | Synchronous — can deny tool calls | | Cursor | ~/.cursor/ | Synchronous — can deny tool calls | | Gemini CLI | ~/.gemini/ or which gemini | Advisory — logs all actions | | OpenCode | ~/.config/opencode/ | Plugin — TypeScript Bun plugin |

Commands

npx custodex                    # Interactive setup wizard
npx custodex init               # Same as above
npx custodex --api-key <key>    # Skip the API key prompt
npx custodex --yes              # Auto-confirm all prompts
npx custodex --status           # Show current configuration
npx custodex --uninstall        # Remove all governance integrations

How it works

1. Detects which AI coding tools are installed on your machine
2. Validates your API key against the Custodex backend
3. Installs governance integrations into each detected tool's configuration
4. Registers an admin agent with your Custodex dashboard

Once installed, every tool call your AI agents make flows through the Custodex governance pipeline:

Agent calls tool  →  Custodex verifies  →  Allow / Deny  →  Log to audit trail

What gets governed

| Action | Scope | Enforcement | |--------|-------|-------------| | File writes & edits | file:write | Synchronous deny | | Shell commands | shell:execute | Synchronous deny | | MCP tool calls | mcp:* | Synchronous deny | | Agent spawning | agent:spawn | Logged | | User prompts | prompt:submit | Logged |

Configuration

Custodex stores its configuration at ~/.custodex/config.json:

{
  "apiKey": "cus_...",
  "baseUrl": "https://a2agov.com",
  "version": "1.0.0",
  "installedAt": 1710201600000
}

Uninstall

npx custodex --uninstall

This cleanly removes all Custodex governance integrations from every configured tool and deletes the ~/.custodex directory.

Requirements

• Node.js >= 18
• At least one supported AI coding tool installed
• A Custodex API key from a2agov.com

Zero dependencies

The CLI has no runtime dependencies — only Node.js built-ins. The published package is 27 KB.

Links

• Dashboard: a2agov.com
• Docs: a2agov.com/docs
• SDK: @custodex/sdk

License

MIT