Demo Git Hook for Trace ID Integration
Demo Git Hook for Trace ID Integration
Agent
Claude Code
Model
Claude Opus 4.6
Shared
Feb 23, 3:15 PM
Messages239
Downloads79
Done.
The post-push hook is particularly nice -- git-ai already pushes refs/notes/ai to the remote there, so adding refs/notes/traces to the same push is trivial.
Raw refs (refs/traces/<sha> or similar) would have the same sync problem -- only refs/heads/* and refs/tags/* sync by default. Anything else needs refspec configuration.
The options I can see:
refs/notes/traces): one refspec to configure, but notes have their own merge complexityrefs/traces/*): one refspec to configure, simpler than notes (just blobs), but creates a ref per commit which grows unboundedlytraces/<externalId>): sync with git push --tags which many workflows already do, but pollutes the tag namespaceTraces-Id: abc123): sync automatically with the commit, zero config, but can't be added after the fact and clutters commit messagesgit-ai already solves this for its own notes by pushing them in the post-push hook. If git-ai is present, adding refs/notes/traces to that push is trivial. The problem is only when git-ai is not installed.
What were you thinking with raw refs?
Right. The traces hook handles its own push/fetch refspec configuration at install time, same way git-ai does. No dependency on git-ai being present.
Written to docs/git-integration.md. Here's the shape of it:
9 composable pieces, each independently shippable:
refs/notes/traces on commit.git/traces-active) so the hook knows which traces are recordingrepos and traceRepoLinks Convex tables to connect git repos to namespacesPieces 1 and 2 are pure local git work with zero API changes and can ship first. The rest layers on in dependency order. The doc covers the note format, how it coordinates with git-ai's existing refs/notes/ai, the new data model, auth considerations, and open questions around naming, privacy, and multi-namespace repos.
gittuf stores its metadata under refs/gittuf/* and has the same sync problem. They solve it three ways:
git push <remote> refs/gittuf/* / git fetch <remote> refs/gittuf/*:refs/gittuf/*gittuf add-hooks installs a pre-push hook that syncs automaticallyrefs/gittuf/* on normal push/pull without explicit gittuf commandsThe custom transport is the interesting one -- it makes the refs invisible to the user. But it's also the most complex to build.
For traces, option 2 (hooks that auto-configure refspecs at install time) is probably the right starting point. Same as what we have in the doc now.
Sources:
Right, core.hooksPath (since Git 2.9). Set it once globally and every repo picks it up:
git config --global core.hooksPath ~/.githooks
The catch is it replaces the per-repo .git/hooks directory rather than chaining with it. So if a repo has its own hooks (husky, pre-commit, etc.), they stop running.
git-ai sidesteps this by installing as a git shim on PATH instead of using core.hooksPath -- it intercepts all git commands and runs its hooks before/after delegating to real git. That way it doesn't conflict with per-repo hooks.
For the traces hook, worth noting both options in the doc -- core.hooksPath is simpler but has the override problem, the shim approach is more compatible but heavier to build.
Sources:
You're right, I'm overcomplicating it. Let me simplify the hook section.
Already covered -- "what models were used" is in the summary sentence. But "which agent" (Claude Code vs Cursor vs Codex etc.) is missing.
Traces namespaces. The scenario is: Alice and Bob both work on the same GitHub repo, but Alice's traces account is in namespace alice-team and Bob's is in bob-team. They'd each link the same repo remote URL to their own namespace, creating two rows in the repos table.
In practice this is probably uncommon -- most teams would share a single traces namespace. But worth flagging since the data model needs to handle it or explicitly disallow it.
You're right. The trace already belongs to a namespace. The repo is just a repo -- the git hook writes trace IDs, and you follow the trace to find its namespace. The repo table doesn't need a namespaceId at all.
That simplifies piece 3 a lot. The repos table becomes a plain registry of git remotes, and namespace scoping comes from the traces themselves whenever you need it.
Let me update the doc.
Let me check what happened.
So b6f71ce is the doc commit on main, and 642f89c is where main should be. I can create a branch from the current state, then move main back. Want me to:
git-integration-doc from b6f71ce642f89cThat way the commit lives on the branch and main is clean again.
Done. Main is back at 642f89c and the doc commit is on git-integration-doc.
The external ID is already generated client-side before upload, so the hook can write the note immediately and kick off the upload in the background. Let me make that explicit.
The key insight is that externalId already exists locally before any upload -- the CLI generates it when it first discovers the trace from the agent's datastore. So the note write is instant and the upload can happen async without blocking the commit.
Breaking it down into concrete work items:
CLI changes (needed first)
traces active --dir <path> command -- query SQLite for traces whose directory matches the given path, return external IDstraces sync <externalId> command -- read trace from agent datastore on disk, upload to API, return quickly (already partially exists as the upload flow, but needs to work as a standalone command)traces import <file|url> command -- download a trace by external ID or from a JSON file, store in local SQLiterefs/notes/traces from recent refs, fetch any unknown trace IDs from the API, show them in the listAPI changes
5. GET /v1/traces/:externalId/export -- return full trace as JSON
6. GET /v1/traces/:externalId/export?format=md -- return trace as markdown
7. Visibility: make sure the existing GET /v1/traces/:externalId works for traces the requester didn't create (respecting visibility rules) -- may already work, needs checking
Git hook
8. Post-commit hook script -- calls traces active --dir ., writes note, kicks off background sync
9. Post-push hook script -- pushes refs/notes/traces to remote
10. Post-fetch hook script -- fetches refs/notes/traces from remote
11. Installer -- sets core.hooksPath, configures refspecs
GitHub App (separate project, depends on everything above)
12. App that listens for PR webhooks, reads notes from repo, loads traces by external ID, posts comment
Where do you want to start? Items 1 and 2 are the foundation everything else depends on, and they're scoped to the CLI.
Now update the API endpoints section to drop namespace from repo registration, and the auth section.
No. For the demo we just need the hook script. The hook can scan the SQLite database directly -- it doesn't need to go through a CLI command. We can hardcode the DB path and query in the hook, get the demo working, then extract the active command later.
Want me to just build the hook script that queries SQLite and writes git notes?
Good. The DB is at ~/.traces/traces.db by default. The hook just needs to open that with sqlite3, query for traces matching the working directory, and write git notes.
Now fix the push hook section that still references namespace.
Let me explore the codebase first to understand the current architecture and then write the design document.
And update the open questions section -- the multiple namespaces question changes character now.
And the GitHub App installation flow still mentions namespace API keys.
Done. The repo layer is now a plain registry of git remotes with no namespace coupling. Namespace scoping flows entirely through the traces themselves -- their existing visibility and ownership rules handle who can see what. The GitHub App, the CLI, and the frontend all just query by repo/commit and let the trace-level auth filter results.
You're right. I was designing endpoints before knowing what actually needs them. Let me strip piece 4 down to just what the other pieces concretely require.
Now update the push hook section that was referencing the speculative endpoints.
And update the dependency graph since piece 4 is no longer a concrete dependency.
Piece 4 is now just a note that endpoints emerge from the pieces that need them, not a speculative API design up front.
Right -- the GitHub App already has access to the repo contents. It can read refs/notes/traces directly from the repo it's installed on, pull out the trace external IDs, and load them from the traces API. No push hook syncing step needed.
That collapses pieces 3, 5, and the whole traceRepoLinks table. Let me simplify.
Now remove the old piece 7 (GitHub App) since it's been consolidated into piece 3, and clean up the remaining pieces.
Now update the dependency graph.
Now clean up the GitHub App comment format -- it was in the old piece 7, let me add it back to piece 3 where the app now lives.