Gryph: Audit Trail for AI Coding Agents

TL;DR

Gryph is a local-first audit trail for AI coding agents. It hooks into Claude Code, Cursor, Gemini CLI, and other agents to log every file read, file write, MCP tool calls, and command execution to a local SQLite database. No cloud telemetry, no data leaving your machine. Query, filter, and replay agent sessions from the terminal.

1
brew install safedep/tap/gryph
2
gryph install

The moment you realize you have no visibility

While working with Claude Code, I noticed that it read .env file followed by executing pythong3 -c .... Then I realised that I was working on a public GitHub issue that is susceptible to prompt injections. Manual analysis revealed that Claude was trying to figure out if it needs to set environmen variables before calling gh CLI to pull data from GitHub. It then cooked up a Python one-liner to extract the required information from the API response JSON.

That moment stuck with me. Not because anything went wrong. The agent was doing its job, gathering context, transforming data from gh api to produce better output. But I had no record of it. No log of which files were read, no trail of what commands ran, no way to answer the question “what exactly did my agent do in that session?” after the fact. Sure, I can investigate Claude Code sessions but that does not scale over time or across team members.

We log SSH sessions. We audit database access. We record who deploys what to production and when. AI coding agents operate with comparable access to sensitive systems, entire codebases, environment variables, shell access, and yet they produce no persistent audit trail.

The gap

This is not a hypothetical concern. Developers grant AI agents access to entire project directories, including configuration files, secrets, and infrastructure definitions. Agents read files to build context, execute shell commands to test code, and write changes across multiple files in a single session.

When something goes wrong, there is no audit capability. A broken build after an agent session means manually diffing files to reconstruct what changed. A security review asking “did any AI tool access our credentials?” has no data source to query. An unexpected npm install or curl in the agent’s output scrolls past and disappears.

Production systems already solved this. Application logs, audit trails, access records. AI coding agents are the gap in that chain.

Gryph

Gryph fills that gap. It installs lightweight hooks into agent configurations and logs every action to a local SQLite database. File reads, file writes, command executions, tool invocations, session boundaries: all captured, all queryable.

The design is deliberately local-first. No cloud service, no telemetry, no data leaving the developer’s machine. Sensitive file access (.env, *.pem, .ssh/, .aws/) is automatically detected and flagged. Secrets in captured content are redacted before storage.

Gryph supports Claude Code, Cursor, Gemini CLI, OpenCode, Windsurf, and Pi Agent. It uses each agent’s native hook system, so there is no custom runtime or wrapper process.

Getting started

Install gryph and set up hooks for your agent. The entire process takes under a minute.

Install gryph:

1
brew install safedep/tap/gryph

Install hooks for Claude Code:

1
gryph install --agent claude-code

The install command produce the following output indicating successful hook installation:

1
[ok]  Claude Code 2.1.69
2
   /Users/dev/.claude
3

4
Installing hooks...
5

6
Installation complete.
7

8
  Database    /Users/dev/Library/Application Support/gryph/audit.db
9
  Config      /Users/dev/Library/Application Support/gryph/config.yaml
10

11
Run 'gryph status' to verify.
12
Run 'gryph logs -f' to watch activity.

That’s it. Gryph is now recording Claude Code activities. Use your agent normally: write code, debug, refactor. Every action flows through the hooks into the local database. Run gryph install without explicit agent flags to set up hooks for all supported agents.

View recent activity:

1
gryph logs

1
2026-03-05 13:45:09   b291330f  claude-code  a87aef84  tool   ToolSearch select:EnterPlanMode
2
2026-03-05 13:45:09   ebf4335d  claude-code  a87aef84  tool   ToolSearch select:EnterPlanMode
3
2026-03-05 13:45:58   0c8d3cb8  claude-code  a87aef84  tool   ToolSearch select:ExitPlanMode
4
2026-03-05 13:45:58   f22d2443  claude-code  a87aef84  tool   ToolSearch select:ExitPlanMode
5
2026-03-05 13:46:01   91b12749  claude-code  a87aef84  tool   ExitPlanMode
6
2026-03-05 13:46:08   667da419  claude-code  a87aef84  notification
7
2026-03-05 13:46:08   b82f8fef  claude-code  a87aef84  tool   ExitPlanMode

Query specific events:

The real power is in filtering. Find every file your agent read matching a pattern, or every command it executed in a time window. Run the query below to find out everytime Claude Code modified its own agent instructions.

1
gryph query --action file_write --file '**/.claude/agents/**'

1
2026-03-05 13:17:49   e169a677  claude-code  052f1858  write  my-project/.claude/agents/grunt... +1 -1
2
2026-03-05 13:17:49   bc3c273a  claude-code  052f1858  write  my-project/.claude/agents/grunt... +1 -1
3
2026-03-05 13:17:57   329115de  claude-code  052f1858  write  my-project/.claude/agents/grunt... +1
4
2026-03-05 13:17:57   b53cd264  claude-code  052f1858  write  my-project/.claude/agents/grunt... +1
5
2026-03-05 13:17:59   b10368bf  claude-code  052f1858  write  my-project/.claude/agents/grunt... +3
6
2026-03-05 13:17:59   97a2c6be  claude-code  052f1858  write  my-project/.claude/agents/grunt... +3
7
2026-03-05 13:18:07   c0ccf6cd  claude-code  052f1858  write  my-project/.claude/agents/corta... +2 -1
8
2026-03-05 13:18:07   ef7434e4  claude-code  052f1858  write  my-project/.claude/agents/corta... +2 -1
9
2026-03-05 13:18:09   4cae6942  claude-code  052f1858  write  my-project/.claude/agents/corta... +1 -1
10
2026-03-05 13:18:09   7bc68ef3  claude-code  052f1858  write  my-project/.claude/agents/corta... +1 -1
11
2026-03-05 13:18:10   790469aa  claude-code  052f1858  write  my-project/.claude/agents/corta... +1 -1
12
2026-03-05 13:18:10   e333439c  claude-code  052f1858  write  my-project/.claude/agents/corta... +1 -1
13
2026-03-05 13:18:11   7708c823  claude-code  052f1858  write  my-project/.claude/agents/corta... +1 -1
14
2026-03-05 13:18:11   c6bb124c  claude-code  052f1858  write  my-project/.claude/agents/corta... +1 -1

Sensitive file detection

Gryph automatically detects when agents access sensitive paths and marks those events. This is not a manual configuration step. Patterns like .env, *.pem, .ssh/**, and .aws/** are recognized out of the box.

1
gryph query --sensitive

Produces output that lists file paths that matches sensitive patterns, along with timestamps and agent names.

1
Results (23 events)
2
──────────────────────────────────────────────────────────────────────────────
3
Time                  Event     Agent        Session   Action Path/Command
4
──────────────────────────────────────────────────────────────────────────────
5
2026-01-29 12:15:06   e3f77a4b  claude-code  2c909e0a  read   /home/user/.env

To see details of the event generated by the agent, use gryph cat <event-id>.

This means the question “did any AI agent access our credentials this week?” has a concrete answer. Query the database, filter by sensitive flag, get a list of files and timestamps.

Custom patterns can be added through gryph configuration to match organization-specific sensitive paths.

Session replay

Every agent action is grouped into sessions with deterministic IDs. When you need to understand exactly what happened during a coding session, replay it.

1
gryph sessions

Produces a list of recent sessions with agent names, timestamps, and event counts.

1
2026-03-05 09:17:30  claude-code  session b9543f1f
2
   5 actions
3

4
2026-03-05 09:16:32  cursor  session f8c6e72d
5
   1 actions
6

7
2026-03-05 09:08:35  claude-code  session 5ae48bf3
8
   2 actions
9

10
2026-03-05 09:04:39  claude-code  session 755b3520
11
   1 actions
12

13
2026-03-05 08:46:25  claude-code  session 17ab0147
14
   357 actions  *  73 files written  *  51 commands

Pick a session and inspect it with diffs:

1
gryph session <session-id> --show-diff

Produces a list of all events in that session with timestamps, event types, file paths or commands, and change status for file writes.

1
#358 2026-03-05 09:32:07  68399759  write
2
    Path: my-project/README.md
3
    Changes: +4
4

5
#359 2026-03-05 09:33:31  6a411075  write
6
    Path: my-project/README.md
7
    Changes: +6
8

9
#360 2026-03-05 09:33:31  9133c910  write
10
    Path: my-project/README.md
11
    Changes: +6
12

13
#361 2026-03-05 09:33:48  3c12fb6c  session_end
14

15
────────────────────────────────────────────────────────────────────────────────────────────
16
Summary: 111 files read, 73 files written, 51 commands (1 errors)

Session replay turns “something broke after the agent session” from a guessing game into a structured investigation. Every file read, every write with its change status, every command with its exit code, in chronological order.

To see what changed during a file write event:

1
gryph diff <event-id>

This produces a unified diff of the file before and after the agent’s modification.

1
Event:     9133c910-f3bd-441b-bbcd-42f04660a8e9
2
Session:   17ab0147-d9ff-4fe6-bae1-e65ae2666e46
3
File:      my-project/README.md
4
Time:      2026-03-05 09:33:31
5

6
--- a/my-project/README.md
7
+++ b/my-project/README.md
8
@@ -1,3 +1,9 @@
9

10
npx skills add safedep/internal-skills
11

12
+
13
+To update installed skills to the latest version:
14
+
15
+npx skills update

Activity dashboard

gryph stats provides an interactive terminal dashboard showing activity patterns across agents and time.

The dashboard surfaces which agents are most active, what types of actions dominate, and how file access distributes over time. Useful for both individual developers tracking their own agent usage and security teams reviewing patterns across a team.

Engineering discipline, not distrust

The argument for AI agent audit trails is the same argument we made for structured logging in production services a decade ago. It is not about distrust. It is about maintaining the same engineering discipline we apply everywhere else.

Production systems are observable because we learned the hard way that you cannot debug, secure, or improve what you cannot see. AI agents are reaching comparable levels of access and autonomy, executing multi-step tasks, running commands, modifying files across repositories. The audit trail becomes more important as capabilities grow, not less.

Local-first is the right default for this. Sending every file read and command execution to a cloud service creates exactly the kind of data exposure you are trying to audit against. The audit trail should live on the developer’s machine, queryable locally, exportable when needed. Gryph supports JSONL export for feeding events into centralized systems like OpenSearch or Splunk when the use case calls for it.

Try it

Gryph is open source under Apache 2.0.

1
# Homebrew
2
brew install safedep/tap/gryph
3

4
# npm
5
npm install -g @safedep/gryph
6

7
# Shell script
8
curl -fsSL https://raw.githubusercontent.com/safedep/gryph/main/install.sh | sh

Install hooks, use your agents, query the trail. The GitHub repo has full documentation: github.com/safedep/gryph.