AI coding agents have no security boundaries. Gryph is building one.
Everyone runs YOLO mode. Nobody checks what happened. Gryph does.
Quick Start · Demo · Supported Agents · Use Cases
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
Other install methods
# 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, timestampstandard: 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).
Files Modified During Installation
Files Modified During Installation
For transparency, these are the files Gryph modifies during gryph install:
| Agent | File Modified | Description |
|---|---|---|
| Claude Code | ~/.claude/settings.json | Adds hook entries to the hooks section |
| Codex | ~/.codex/hooks.json | Creates or updates hooks configuration |
| Cursor | ~/.cursor/hooks.json | Creates or updates hooks configuration |
| Gemini CLI | ~/.gemini/settings.json | Adds hook entries to the hooks section |
| OpenCode | ~/.config/opencode/plugins/gryph.mjs | Installs JS plugin that bridges to gryph |
| Windsurf | ~/.codeium/windsurf/hooks.json | Creates or updates hooks configuration |
Backups
Existing files are automatically backed up before modification. Backups are stored in the Gryph data directory:
| Platform | Backup Location |
|---|---|
| macOS | ~/Library/Application Support/gryph/backups/ |
| Linux | ~/.local/share/gryph/backups/ |
| Windows | %LOCALAPPDATA%\gryph\backups\ |
Backup files are named with timestamps (e.g., settings.json.backup.20250131120000).
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