AIM

Minimal command-first prototype for Agent Identity & Access Management.

AIM keeps the first surface small: Codex uses a plugin skill to install a local PreToolUse hook, turn natural-language "block this" requirements into policy rows, and deny matching Codex tool calls before they execute. There is no local server and no UI.

Install

Run the public CLI without installing:

npx -y @samirosamsam/aim@latest demo

Install the CLI globally:

npm install -g @samirosamsam/aim
aim demo

Install the Codex plugin from this repo:

codex plugin marketplace add tototozip/AIM --ref main
codex plugin add aim@aim

Then start a new Codex thread, run /hooks, trust the AIM hook if Codex asks, and invoke @aim.

Example:

@aim empêche git push

To test it, ask Codex to run:

git push origin main --dry-run

The call should be denied before Bash executes.

Codex Guardrail

Install or refresh the local Codex hook:

npx -y @samirosamsam/aim@latest setup

This is only needed when using the CLI without the Codex plugin. The plugin already bundles hooks/hooks.json.

If Codex says hooks need review, run /hooks, inspect the AIM hook, and trust it.

Add a deterministic guardrail from natural language:

npx -y @samirosamsam/aim@latest rule add 'empêche git push'
npx -y @samirosamsam/aim@latest rule add 'empêche de modifier package.json'
npx -y @samirosamsam/aim@latest rule add 'empêche les calls GitHub qui ajoutent des collaborators'

For SaaS data targets described by a title or label, use Codex/provider tools first to resolve the concrete resource, then write the rule with capture:

npx -y @samirosamsam/aim@latest capture \
  --provider notion \
  --tool fetch \
  --args '{"url":"https://www.notion.so/..."}' \
  --effect deny \
  --agent codex \
  --connection notion:codex \
  --policy ~/.codex/aim/policy.json

Codex then calls the AIM hook before supported tool calls. A blocked Bash call returns the Codex PreToolUse deny shape:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "AIM blocked Bash: Block write on bash/git push*."
  }
}

Run

npm test
node ./bin/aim.js demo

CLI

Draft grants without writing policy:

npx -y @samirosamsam/aim@latest compile 'Block Notion read access to "workspace/shared/legal/*"' --json

Capture a concrete MCP call as a resource/action rule:

npx -y @samirosamsam/aim@latest capture \
  --provider github \
  --tool list_repository_collaborators \
  --args '{"owner":"tototozip","repo":"AIM"}' \
  --effect deny \
  --agent 'spiffe://local/agent/demo/codex' \
  --connection 'github:prod' \
  --json

Append grants to a policy file:

npx -y @samirosamsam/aim@latest add 'Allow Notion read access to "workspace/shared/*"' \
  --policy aim.policy.json \
  --agent 'spiffe://local/agent/demo/codex' \
  --json

Append a captured MCP rule to a policy file:

npx -y @samirosamsam/aim@latest capture \
  --provider github \
  --tool list_branches \
  --args '{"owner":"tototozip","repo":"AIM"}' \
  --effect allow \
  --policy aim.policy.json \
  --agent 'spiffe://local/agent/demo/codex' \
  --connection 'github:prod' \
  --json

Check a representative MCP call:

npx -y @samirosamsam/aim@latest check \
  --policy aim.policy.json \
  --agent 'spiffe://local/agent/demo/codex' \
  --connection 'notion:prod' \
  --tool 'pages.read' \
  --resource 'workspace/shared/legal/term-sheet' \
  --access read \
  --json

Authorize using raw MCP call args:

npx -y @samirosamsam/aim@latest authorize \
  --policy aim.policy.json \
  --agent 'spiffe://local/agent/demo/codex' \
  --connection 'github:prod' \
  --provider github \
  --tool list_branches \
  --args '{"owner":"tototozip","repo":"AIM"}' \
  --json

Codex Plugin

This repo is shaped as a Codex plugin:

• .codex-plugin/plugin.json declares the plugin package.
• skills/aim/SKILL.md teaches Codex to install the hook and add rules with the local aim command instead of inventing grant JSON manually.
• hooks/hooks.json bundles the PreToolUse hook for plugin installs.
• bin/aim.js is the command surface.

The current prototype implements prompt-to-guardrail compilation, Codex PreToolUse blocking for Bash, apply_patch, and MCP tool calls, MCP-call capture, JSON policy writes, deny-overrides precedence, and decision audit rows. It intentionally skips the real MCP proxy, token vault, OAuth, Cedar, and hosted control plane.