gryph

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. When something goes wrong, there is no audit trail.

Gryph fixes that. It hooks into agents, logs every action to a local SQLite database, and provides powerful querying to understand, review, and debug agent activity. 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

Pre-built binaries for macOS, Linux, and Windows are available on the GitHub Releases page.

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

| Agent | Hook Support | | --- | --- | | Claude Code | Full (PreToolUse, PostToolUse, Notification) | | Codex | Full (PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, Stop) | | Cursor | Full (file read/write, shell execution, MCP tools) | | Gemini CLI | Full (BeforeTool, AfterTool, Notification) | | OpenCode | Full (tool.execute, session events) | | Pi Agent | Full (tool_call, tool_result, session events) | | Windsurf | Full (file read/write, commands, MCP tools) |

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

[features]
codex_hooks = true

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

| Scenario | How Gryph Helps | | --- | --- | | Replay the full session | git diff shows final changes. Gryph shows the full sequence: what the agent read, what it ran, what it wrote and reverted, and in what order. | | Catch invisible side effects | Agents run shell commands that leave no trace in git (npm install, curl, rm). gryph query --action exec surfaces them all. | | Sensitive file access | Gryph flags access to .env, *.pem, *.key, and similar files automatically. Actions are logged but content is never stored. | | Security review | Export events to your SIEM, or use the OpenSearch observability example for centralized dashboards and threat detection alerts. | | Cost and token tracking | Track per-session token usage and estimated costs across models and agents. See docs | | Compare agents | Filter by --agent to see how different agents approach the same task: which reads more, which runs more commands, which costs more. |

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.

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
gryph query --action file_write --show-diff              # Include file diffs

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 (default)
• standard : Adds diff stats, exit codes, truncated output
• full : Adds fil