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.leveltofullto 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_hooksfeature 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 outputfull: Adds fil