agentperm 0.1.0

Permission policy mediator for Claude Code, Codex, OpenCode, and Gemini CLI.

agentperm

One permission policy file for coding agents. Configure Claude Code, Codex CLI, or OpenCode to call the bridge from their hook systems, and they can all consult ~/.agent-permissions.jsonc before tools run — so the same allow / ask / deny rules apply everywhere.

Why

Every agent ships its own permission system, and none of them parse compound shell commands the way a shell does. cat foo 2>/dev/null | head -60 is two read-only segments separated by a pipe, but the native config typically can't reason about pipes, redirects, &&, for ... do ... done, or bash -c "..." — so it asks, every time. The bridge parses the command with the Tree-sitter Bash grammar, evaluates each executable segment against your policy, and returns a single decision.

It also gives you one source of truth instead of four, plus a richer rule grammar (e.g. "ask before sed -i, allow sed otherwise").

Install

pipx install agentperm
# or
uv tool install agentperm

Then:

agentperm import    # pulls existing native rules into ~/.agent-permissions.jsonc
agentperm install   # wires the bridge into Claude Code, Codex, OpenCode, and Gemini hooks
agentperm edit      # opens the policy in $EDITOR (creates a default if missing)

install auto-detects whether you use Rulesync — if ~/.rulesync/ exists, it merges hook entries into ~/.rulesync/hooks.json and you re-run rulesync to materialise per-tool configs. Otherwise it writes per-tool configs (~/.claude/settings.json, ~/.codex/hooks.json+config.toml, ~/.gemini/settings.json) directly. The OpenCode plugin shim is always installed at ~/.config/opencode/plugins/agentperm.js because rulesync has no schema for permission.ask plugins. Pass --mode rulesync|direct to override detection or --dry-run to preview.

Per-project overrides live in <project>/.agent-permissions.jsonc — both files merge at decision time, deny wins.

Quickstart

{
  "version": 1,
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(ls:*)",
      "Bash(cat:*)",
      "Read",
      "Grep",
      "WebFetch(domain:github.com)"
    ],
    "ask": [
      {
        "tool": "Bash",
        "command": ["sed", "gsed"],
        "when": { "hasOption": ["-i", "--in-place"] },
        "reason": "sed in-place editing changes files"
      }
    ],
    "deny": [
      "Bash(sudo:*)",
      "Bash(rm -rf /*)"
    ]
  }
}

A compound like cat foo 2>&1 | head -60 passes through silently with the policy above — every segment matches an allow rule, the redirect is a safe 2>&1 fd-dup, and the bridge returns allow.

sed -i s/foo/bar/ x.txt surfaces a prompt with the rationale "sed in-place editing changes files" — the ask rule beats the allow rule on sed.

rm -rf /tmp/* is denied without prompting.

Bypass mode (zellij)

A per-pane "skip prompts" toggle for users running their agents inside zellij. Bind a key to flip a flag file for the focused pane; while the flag is on, agentperm coerces Ask and NoOpinion verdicts to Allow — but only in that pane, and Deny rules still bite. (Claude's own bypassPermissions is different: there agentperm defers entirely and lets Claude handle everything.) The toggle and indicator live in a small WASM plugin shipped at zellij-plugin/.

Documentation

• Architecture — domain model, AST parsing, aggregation, bypass coercion
• Policy reference — full grammar of .agent-permissions.jsonc
• CLI reference — install, import, check, edit, pane bypass
• Adapter notes — agent-specific behavior and limits
• Troubleshooting — diagnosing prompts, the trace env var, common pitfalls
• zellij plugin — per-pane bypass toggle and indicator
• Contributing — dev setup, tests, PR conventions
• Changelog

What it doesn't do

• Manage MCP servers — use Rulesync, native agent config, or your own dotfile tooling.
• Replace native permission settings — those keep working as fast paths. The bridge layers on top.
• Sandbox commands — the bridge is a policy engine, not an enforcement engine. Commands the agent decides to run still run with your shell's privileges.

License

MIT — see LICENSE.