agd — Agent Graph Database

Git for AI agents. A content-addressed DAG store that captures what agents did and why.

agd records every LLM interaction as a trace — messages observed, messages produced, tool calls, and their causal relationships. When you open a PR, reviewers can see exactly what the AI did, not just the code diff.

Quick Start

1. Install the binary

Download from Releases and place on your PATH:

# macOS (Apple Silicon)
curl -L https://github.com/BlueHotDog/agd/releases/latest/download/agd-aarch64-macos -o /usr/local/bin/agd
chmod +x /usr/local/bin/agd

# macOS (Intel)
curl -L https://github.com/BlueHotDog/agd/releases/latest/download/agd-x86_64-macos -o /usr/local/bin/agd
chmod +x /usr/local/bin/agd

# Linux (x86_64)
curl -L https://github.com/BlueHotDog/agd/releases/latest/download/agd-x86_64-linux -o /usr/local/bin/agd
chmod +x /usr/local/bin/agd

# Linux (ARM64)
curl -L https://github.com/BlueHotDog/agd/releases/latest/download/agd-aarch64-linux -o /usr/local/bin/agd
chmod +x /usr/local/bin/agd

2. Add the OpenCode plugin

Copy the plugin into your project:

mkdir -p .opencode/plugins
curl -L https://raw.githubusercontent.com/BlueHotDog/agd/main/.opencode/plugins/agd.ts -o .opencode/plugins/agd.ts

The plugin auto-initializes the .agd/ store and auto-discovers agd on PATH. No config needed — OpenCode loads plugins from .opencode/plugins/ automatically.

3. Commit the store

git add .agd/ .opencode/plugins/agd.ts
git commit -m "add agd agent tracing"

4. Use OpenCode normally

Every LLM interaction is now traced. View traces for your current branch:

agd log --branch my-feature-branch
agd log --branch my-feature-branch --format markdown

PR Integration (GitHub Actions)

Add this workflow to automatically post agent traces as PR comments:

mkdir -p .github/workflows
curl -L https://raw.githubusercontent.com/BlueHotDog/agd/main/.github/workflows/agd-trace.yml -o .github/workflows/agd-trace.yml
git add .github/workflows/agd-trace.yml
git commit -m "add agd trace to PRs"

When a PR is opened or updated, the workflow builds agd, runs agd log --branch <pr-branch> --format markdown, and posts the result as a PR comment.

How It Works

agd stores three object types in a content-addressed DAG:

• Blob — raw data (tool args, tool results, large text)
• Message — a message with role and typed content parts (text, thinking, tool calls, tool results, images, files)
• Action — a causal node: "agent X in session Y observed messages [A,B] and produced messages [A,B,C]"

Actions chain via parent links, forming a DAG per session. Sessions are grouped by git branch via refs.

Action(a3) → parent → Action(a2) → parent → Action(a1)
  session: ses_abc123          session: ses_abc123
  agent: build                 agent: build
  tag: llm.stream              tag: llm.stream
  observed: [m1,m2,m3,m4]     observed: [m1,m2]
  produced: [m1,m2,m3,m4,m5]  produced: [m1,m2,m3]

The OpenCode plugin captures this automatically — no code changes needed in your project.

CLI Reference

agd init                          Initialize a .agd/ store
agd blob create < data            Store a blob from stdin
agd message create --role <role> --text <text> [...]
                                  Store a message
agd action create --session <id> --agent <id> --tag <tag> [...]
                                  Store an action
agd show <hash>                   Show any object by hash
agd log [--session <id>] [--branch <name>] [--format oneline|markdown]
                                  Walk and display actions
agd ref list                      List all refs
agd ref set <name> <hash>         Set a ref
agd ref get <name>                Get a ref
agd ref delete <name>             Delete a ref

Building from Source

Requires Zig 0.15.2:

zig build              # debug build → zig-out/bin/agd
zig build test         # run all tests
zig build release      # cross-compile for linux/macos × x86_64/aarch64