omamori 0.10.0

AI Agent's Omamori — protect your system from dangerous commands executed via AI CLI tools
Documentation

omamori

CI crates.io homebrew License

Safety guard for AI CLI tools. Blocks dangerous commands — and resists being disabled.

Hook check completes in <0.1ms — no perceivable latency.

When AI tools like Claude Code, Codex, or Cursor run shell commands, omamori intercepts destructive operations and replaces them with safe alternatives.

Unlike other guards, omamori defends itself — AI agents cannot disable or bypass its protection (#22).

macOS only — Terminal commands are never affected; omamori only activates when it detects an AI tool's environment variable. See Tool Compatibility for supported AI tools and CI coverage.

omamori demo

Quick Start

# Install (macOS)
brew install yottayoshida/tap/omamori

# Setup (shims + hooks + config — all in one)
omamori install --hooks

# Add to your shell profile (~/.zshrc or ~/.bashrc)
export PATH="$HOME/.omamori/shim:$PATH"

# Verify everything is healthy
omamori doctor

That's it. Works with Claude Code Auto mode — no extra config needed.

Requires omamori >= 0.9.0 for doctor and explain commands. For Cursor and Codex CLI, see Tool Compatibility.

What It Blocks

Command Pattern Action
rm -r, -rf, -fr, --recursive trash — move to macOS Trash
git reset --hard stash-then-exec — git stash first
git push --force, push -f block
git clean -f, clean --force block
chmod 777 block
find -delete, --delete block
rsync --delete + 7 variants block

--delete, --del, --delete-before, --delete-during, --delete-after, --delete-excluded, --delete-delay, --remove-source-files

All rules are customizable via TOML config. See Configuration below.

Tool Compatibility

Supported tiers

Tier Tools Coverage
Supported Claude Code, Codex CLI, Cursor E2E tested. Layer 1 + Layer 2. Auto mode compatible.
Community Gemini CLI, Cline, others Layer 1 only. Not E2E tested.
Fallback Any tool setting AI_GUARD=1 Layer 1 only.

The demo image above is a Claude Code capture; the same block / log-only / trash behaviour applies on Codex CLI and Cursor when their env vars are detected.

Tool-specific notes

  • Claude Code: hooks applied automatically. No action needed.
  • Codex CLI: hooks and config auto-configured during install. Auto-sync regenerates wrappers on brew upgrade.
  • Cursor: after brew upgrade, re-merge the hook snippet from ~/.omamori/hooks/cursor-hooks.snippet.json into .cursor/hooks.json.

Platforms

macOS only at runtime — shim paths and Trash integration are macOS-specific. CI verifies contributors' PRs on macOS + Ubuntu (#[cfg(unix)] regressions caught before merge). Windows is not supported.

How omamori handles new / renamed tools

omamori routes by payload shape (tool_input.command / cmd / file_path / path / url), not by tool name. A renamed AI tool carrying a command field still reaches the full pipeline; unrecognised shapes still allow but emit unknown_tool_fail_open audit events. Review with omamori audit unknown or check omamori doctor's 30-day count line.

For the full shape catalogue, scope, known operational noise (legitimate tools like Glob / Task landing in fail-open), and the strict-mode trade-off, see SECURITY.md → Hook Coverage.

How It Works

AI CLI tool → CLAUDECODE=1 → rm -rf src/
                                ↓
                          [omamori shim]
                                ↓
                        blocked (protected path)

Terminal → rm -rf src/
                ↓
          [/usr/bin/rm]
                ↓
          deleted normally

Layer 1 — PATH shim: symlinks for rm, git, chmod, find, rsync point to omamori. Rules apply only when an AI environment variable is detected.

Layer 2 — Hooks: evaluates commands against the same rules as Layer 1, with three additional capabilities:

  • Recursively unwraps shell wrappers (sudo env bash -c "..." → extracts inner command).
  • Blocks pipe-to-shell patterns (curl URL | bash, curl URL | sudo bash, and other transparent-wrapper variants — see SECURITY.md).
  • Blocks dynamic command generation (bash -c "$(cmd)").

Available for Claude Code, Cursor, and Codex CLI.

Audit log: records every command decision in a tamper-evident log — if an AI agent modifies any entry, the chain breaks and tampering is detected.

  • Tamper-evident JSONL log at ~/.local/share/omamori/audit.jsonl.
  • HMAC-SHA256 signed and hash-chained — tampering breaks the chain and is detected.
  • Per-install secret; file paths HMAC-hashed (never stored in plaintext).
  • Set retention_days in config to automatically prune old entries — chain integrity is preserved across pruning.
  • Logging enabled by default; retention is opt-in via config.

Performance: hook check completes in well under 0.1ms — typically ~1 µs to block, ~57 µs to allow. Subprocess startup by the AI tool itself dominates the cost, so omamori adds no perceivable latency. Measured locally with cargo bench; see #124 for methodology and benches/ for reproducible harnesses.

Self-defense: AI agents cannot config disable, uninstall, or edit config.toml while detected. Hooks block env var unsetting, config modification, and audit log/secret access via shell commands. This is a key differentiator from other CLI guards — omamori assumes adversarial AI behavior and defends against it.

Auto mode compatible: works seamlessly with Claude Code's Auto mode — safe commands proceed without prompts, dangerous commands are still hard-blocked.

Auto-sync: after brew upgrade, the shim detects version mismatch and auto-regenerates hook files on the next invocation.

Core policy: the 7 built-in rules cannot be disabled via config.toml — an AI agent setting enabled = false is silently ignored. For legitimate overrides, see omamori override in CLI Reference.

Integrity monitoring (omamori status): verifies all defense layers are intact — shims, hooks, config, core policy, PATH order. Detects tampering including subtle hook edits where the version comment is preserved but the body is rewritten.

File protection: AI Edit/Write operations on omamori's own files (config, hooks, audit log, integrity baseline, Claude Code settings.json) are blocked. See SECURITY.md for the full protected file list.

Real-world Effect

omamori is dogfooded daily on the developer's own setup. Recent observed cases:

2026-04-23: Codex CLI tried to read config.toml during MCP re-auth

When Codex CLI ran mcp login notion, it first attempted rg / sed against ~/.codex/config.toml to find the auth setting. omamori hooks blocked both reads ("blocked attempt to edit Codex config"). Codex then tried to use omamori explain -- ... as an oracle to probe protection — also blocked by oracle-attack prevention. Codex pivoted to codex mcp --help → codex mcp login notion and completed OAuth via the browser. No protection bypassed; user-side hint preserved for after-the-fact verification.

Full transcript: docs/dogfood/2026-04-23-codex-notion-mcp-reauth.md.

These are honest snapshots of a single developer's environment, not benchmark claims.

Configuration

Context-aware actions

omamori can adjust actions based on what the command targets:

Command Without context With context
rm -rf target/ trash log-only (regenerable)
rm -rf src/ trash block (protected)
git reset --hard (no changes) stash-then-exec log-only (git-aware)

Opt-in: add [context] to ~/.config/omamori/config.toml. Built-in lists for regenerable (target/, node_modules/, etc.) and protected (src/, .git/, .env, etc.) paths activate automatically.

[context]
# Built-in defaults activate with just [context].
# To customize, specify your own lists (replaces built-in defaults):
# regenerable_paths = ["target/", "node_modules/", "my-cache/"]
# protected_paths = ["src/", "lib/", ".git/", ".env", ".ssh/", "secrets/"]

Note: specifying regenerable_paths or protected_paths replaces the built-in defaults (not appends). Include the built-in entries you want to keep.

Security features: symlink defense via canonicalize(), path traversal normalization, NEVER_REGENERABLE hardcoded list, fail-close on errors.

Rule configuration

Built-in rules are always inherited. Only write the rules you want to change:

omamori config list                          # show all rules
omamori config disable git-push-force-block  # disable a rule
omamori config enable git-push-force-block   # restore default
omamori test                                 # verify policy

Or edit ~/.config/omamori/config.toml directly. Config is auto-created by install --hooks. See omamori init --stdout for the full template.

Disable a rule:

[[rules]]
name = "git-push-force-block"
enabled = false

Move files to a custom directory:

[[rules]]
name = "rm-to-backup"
command = "rm"
action = "move-to"
destination = "/tmp/omamori-quarantine/"
match_any = ["-r", "-rf", "-fr", "--recursive"]

Override an existing rule:

[[rules]]
name = "rm-recursive-to-trash"
action = "move-to"
destination = "/tmp/omamori-quarantine/"

Enable audit retention (prunes entries older than N days):

[audit]
retention_days = 90  # 0 = keep all (default). Minimum 7 days.

Enable strict mode (block shim-intercepted commands when HMAC secret is unavailable):

[audit]
strict = true  # default: false. Hook-only commands (ls, cat, etc.) are not affected.

Notes: config requires chmod 600. Destinations must be absolute paths on the same volume. System directories and symlinks are rejected.

CLI Reference

omamori install [--hooks]                # Setup shims + hooks + config (re-run after brew upgrade for Cursor)
omamori doctor [--fix] [--verbose] [--json]  # Diagnose and auto-repair installation
omamori explain [--json] -- <cmd...>     # Show what would happen to a command and why
omamori test [--config PATH]             # Verify policy rules
omamori status [--refresh]               # Health check all defense layers
omamori exec [--config PATH] -- CMD      # Run command through policy engine

omamori report [--last 7d] [--json] [--verbose]  # Aggregate audit summary (1d–90d)

omamori audit verify                     # Verify hash chain integrity (exit 0/1/2)
omamori audit show [--last N] [--json]   # View recent audit entries (default: last 20)
omamori audit show --all                 # View all entries
omamori audit show --rule <name>         # Filter by rule (substring match)
omamori audit show --provider <name>     # Filter by provider

omamori config list                      # Show rules with status
omamori config disable <rule>            # Disable a rule
omamori config enable <rule>             # Re-enable a rule
omamori override disable <rule>          # Override a core safety rule
omamori override enable <rule>           # Restore a core safety rule

omamori init [--force] [--stdout]        # Create/reset config
omamori uninstall                        # Remove shims + hooks
omamori hook-check [--provider NAME]     # Hook detection engine (used internally by hooks)
omamori cursor-hook                      # Cursor hook handler
omamori --version                        # Show version

Scope and Limitations

Sandbox complementarity

omamori operates at the semantic layer — it understands what a command does (Layer 1: shim, Layer 2: hooks). A filesystem sandbox operates at the OS boundary — it restricts where processes can read and write. These are complementary:

  • omamori catches rm -rf src/ before it runs (semantic: "dangerous command").
  • A sandbox prevents damage if something slips through (boundary: "this process cannot write outside /tmp").

For defense in depth, combine omamori with your AI tool's sandbox (Codex CLI sandbox (default-on), Claude Code /sandbox, Cursor agent sandbox) or nono.

Structural limitations

These are inherent to the PATH shim approach:

  • Full-path execution (/bin/rm) bypasses the shim — mitigated by Layer 2 hooks.
  • sudo changes PATH — omamori blocks when it detects elevated execution.
  • Interpreter commands (python -c "shutil.rmtree(...)") — not detected. Decided out of scope per #74: zero real-world incidents in target tools.
  • Obfuscated commands (base64, variable indirection) — cannot be detected by static analysis.
  • AI self-bypass — config disable / uninstall are blocked; direct file editing blocked by hooks (Claude Code only).

For what omamori does not catch — by design or by structural limit — and for the full security model and bypass corpus, see SECURITY.md.

Contributing & License

Bug reports, security disclosures, and PRs welcome — see CONTRIBUTING.md for branch naming, the SHA-pin policy, and the local pre-PR gate (./scripts/pre-pr-check.sh). Releases are reproducible: Cargo.lock is tracked, every CI cargo invocation runs with --locked, and every GitHub Action uses: ref is pinned to a 40-char SHA (Dependabot keeps them current). See SECURITY.md for the five invariants that govern AI-assisted contributions.

Licensed under either of Apache License, Version 2.0 or MIT license at your option.