README.md

AI coding agents have no security boundaries. Gryph is building one.

Everyone runs YOLO mode. Gryph enforces guardrails and keeps the audit trail.

Quick Start · Demo · Supported Agents · Use Cases · Security Policy

AI coding agents (Claude Code, Cursor, Windsurf, Gemini CLI, OpenCode) can read any file, write anywhere, and execute arbitrary commands on a developer's machine. They run dozens of tool calls per session. There are no boundaries on what they can do and no audit trail when something goes wrong.

Gryph fixes that. It hooks into agents, enforces YAML policy rules that block, warn, or guide actions in real time, and logs every event to a local SQLite database for review and audit. All data stays local. No cloud, no telemetry.

The Problem

A developer asks Claude Code to refactor a module. It runs 47 tool calls in 90 seconds. Then the tests fail.

• Which files did the agent read before making changes?
• Did it run shell commands that were not expected?
• Did it touch config files, secrets, or CI pipelines?
• What did the file look like before and after?

Without Gryph, developers are left guessing. With Gryph, gryph logs shows everything.

Quick Start

# Install Gryph with one command
curl -fsSL https://raw.githubusercontent.com/safedep/gryph/main/install.sh | sh

# Setup gryph for available agents
gryph install                    # hooks into all detected agents
gryph status                     # verify setup

# ... use your AI agent normally ...
gryph logs                       # see what happened

# Homebrew (macOS/Linux)
brew install safedep/tap/gryph

# npm
npm install -g @safedep/gryph

# Go
go install github.com/safedep/gryph/cmd/gryph@latest

Tip: Set logging.level to full to see file diffs and raw events: gryph config set logging.level full. See Configuration for details.

Supported Agents

Note: Codex hooks require enabling the codex_hooks feature flag in your Codex configuration (~/.codex/config.toml):

[features]
codex_hooks = true

Note: Devin CLI also loads Claude Code hooks from ~/.claude/settings.json by default (read_config_from.claude). When gryph hooks are installed for both agents, one Devin session emits devin events and claude-code events. Disable read_config_from.claude in the Devin user config to keep one stream.

One command installs hooks for all detected agents. No per-agent setup required.

See It in Action

Live streaming of agent actions as they happen with gryph logs --live:

Use Cases

How It Works

Gryph installs lightweight hooks into AI coding agents. When an agent reads a file, writes a file, or executes a command, the hook sends a JSON event to Gryph. Events are stored in a local SQLite database and can be queried anytime. Because Gryph hooks into both pre-tool and post-tool events, it captures the full lifecycle of every agent action.

Security Policy

Beyond logging, Gryph can enforce a YAML policy over agent actions. Rules can block, warn, guide, or allow based on action type, file path, command pattern, tool name, agent, project, and CEL expressions over per-session counters. Blocked actions never reach the agent's tool, guidance is delivered back to the agent as stderr text, and every decision is persisted.

gryph policy init          # write the example policy to the global config dir
gryph policy edit          # open it in $EDITOR and scaffold if missing
gryph policy validate
gryph policy test --action file_write --path ./secrets/db.env
gryph config set policy.enabled true

See security policy for more details.

Commands

For a complete reference of all commands and flags, see CLI Reference.

Install and Uninstall Hooks

gryph install                      # Install hooks for all detected agents
gryph install --dry-run            # Preview what would be installed
gryph install --agent claude-code  # Install for a specific agent
gryph uninstall                    # Remove hooks from all agents
gryph uninstall --purge            # Remove hooks and purge all data
gryph uninstall --restore-backup   # Restore original hook config from backup

View Recent Activity

gryph logs                     # Last 24 hours
gryph logs --today             # Today's activity
gryph logs --agent claude-code # Filter by agent
gryph logs --follow            # Stream events in real time
gryph logs --format json       # Output as JSON

Query Historical Data

gryph query --file "src/auth/**" --action file_write    # Find writes to specific files
gryph query --action exec --since "1w"           # Commands run in the last week
gryph query --session abc123                             # Activity from a specific session
gryph query --action file_write --today --count          # Count matching events
gryph query --command "npm *" --since "1w"               # Filter by command pattern

Sessions

gryph sessions                        # List all sessions
gryph session <session-id>            # View detailed session history
gryph session <session-id> --show-diff # View session with file diffs

Diffs and Export

gryph diff <event-id>                                  # See what changed in a write event

gryph export                                           # Export last hour as JSONL to stdout
gryph export --since "1w" -o audit.jsonl               # Export last week to file
gryph export --agent claude-code --sensitive            # Include sensitive events
gryph export --since 1d | jq -r '.action_type' | sort | uniq -c | sort -rn

Each exported line includes a $schema field pointing to event.schema.json. Sensitive events are excluded by default; use --sensitive to include them. See CLI Automation for more jq recipes.

Statistics Dashboard

gryph stats                               # Interactive stats TUI
gryph stats --since 7d                    # Stats for the last 7 days
gryph stats --since 30d --agent claude-code # Filter by agent

Data Management

gryph retention status         # View retention policy and stats
gryph retention cleanup        # Clean up old events
gryph retention cleanup --dry-run # Preview what would be deleted
gryph self-log                 # View gryph's own audit trail

Health Check

gryph status  # Check installation status
gryph doctor  # Diagnose issues

Configuration

Gryph works out of the box. Configuration is optional.

gryph config show                       # View current config
gryph config get logging.level          # Get a specific value
gryph config set logging.level full     # Set logging level
gryph config reset                      # Reset to defaults

Logging levels:

• minimal : Action type, file path, timestamp
• standard : Adds diff stats, exit codes, truncated output (default)
• full : Adds file diffs, raw events, conversation context

Sensitive files (.env, *.pem, *secret*, etc.) are detected automatically. Actions on these files are logged but content is never stored.

Privacy

All data stays on the local machine. There is no cloud component, no telemetry, no tracking.

• Sensitive file detection : Files matching .env, *.pem, *.key, *secret*, .ssh/**, .aws/** and more are automatically flagged. Actions are logged but content is never stored.
• Content redaction : Passwords, API keys, tokens, and credentials are automatically redacted from logged output.
• Content hashing : File contents are stored as SHA-256 hashes by default, allowing identity verification without storing actual content.
• Local-only storage : SQLite database with configurable retention (default 90 days).

Community

Questions, feedback, or contributions are welcome.

• Discord : Join the SafeDep community
• Issues : Report bugs or request features
• Contributing : See CONTRIBUTING.md for guidelines

If Gryph is useful, consider giving it a star. It helps others discover the project.

Star History

License

Apache 2.0. See LICENSE for details.

Built by SafeDep · Discord · Star on GitHub