Add Git Metadata to Traces and Prepare Sync
Add Git Metadata to Traces and Prepare Sync
Agent
Claude Code
Model
Claude Opus 4.6
Shared
Feb 23, 5:21 PM
Messages379
Implement the following plan:
Traces store a directory path but no git context. When a trace gets shared or linked to a PR, we can't tell which repo, branch, or ref it came from without re-deriving it from the directory. Adding gitRemoteUrl, gitBranch, and gitRef to the trace schema lets us store this at discovery time and send it up with the trace to the server, where it becomes queryable.
This touches three layers: CLI local storage (SQLite), the API sync path, and the Convex backend schema.
New branch from main (or from feat/traces-active-command if that has merged).
cli/src/types.tsAdd three optional fields to TraceMetadata:
cli/src/core/migrations.tsBump CURRENT_SCHEMA_VERSION to 4. Add migration:
cli/src/core/event-store.tsgit_remote_url TEXT, git_branch TEXT, git_ref TEXT to the CREATE TABLE statementupsertTrace(): add the three columns to INSERT and ON CONFLICT (use COALESCE to preserve existing values)updateTrace(): add the three fields to the dynamic update buildergetTrace(): add the three columns to the SELECTlistTraces(): add the three columns to the SELECTgitRemoteUrl) in TypeScript and snake_case (git_remote_url) in SQL, matching the existing shared_url/sharedUrl patterncli/src/core/git.tsA small utility that resolves git metadata from a directory path:
Runs git -C <dir> config --get remote.origin.url, git -C <dir> rev-parse --abbrev-ref HEAD, and git -C <dir> rev-parse HEAD via Bun.spawnSync (or child_process.execSync). Returns empty object if directory isn't a git repo or commands fail. Each command runs independently so partial results are fine (e.g. a repo with no remote still returns branch and ref).
cli/src/adapters/claude-code/v1.tsIn getTraces() and getTraceIndexBatch(), after setting directory on each trace, call resolveGitInfo(directory) and set the three fields. This happens at scan time so the data is captured when the trace is fresh.
Performance: resolveGitInfo runs three quick local git commands. The adapters already do file I/O per trace, so this adds minimal overhead. We can cache by directory (most traces in a batch share the same directory) to avoid redundant calls.
cli/src/services/api.tsExtend SyncTracePayload with the three new fields:
Update buildTracePayload() to include them from TraceMetadata. Update syncTraceMetadata() to send them in the request body.
packages/shared/src/api/v1/openapi.jsonAdd gitRemoteUrl, gitBranch, gitRef as optional string properties to:
TraceCreateRequestTraceUpsertRequestTraceDetail (in the allOf extension object, alongside projectPath)Then regenerate types: cd packages/shared && bun run generate:api
api/convex/lib/validators.tsAdd to both TraceCreateSchema and TraceUpsertSchema:
api/convex/schema.tsAdd to the traces table definition:
Add an index for querying by repo: .index("by_gitRemoteUrl", ["gitRemoteUrl"])
api/convex/internal/sync.tsAdd the three fields to traceInput args. In upsertTrace handler, include them in both the insert and the conditional update block (same pattern as projectPath).
api/convex/services/traces.tsmapTraceDetail(): include gitRemoteUrl, gitBranch, gitRef in the returned objectcreateTrace(), upsertTrace(), updateTrace(): pass the three fields through to the internal mutationcli/src/core/git.test.ts: test resolveGitInfo with a real temp git repo (init, add remote, commit, check all three fields resolve). Test with non-git directory returns empty. Test with repo that has no remote returns branch+ref but no remoteUrl.cli/src/core/migrations.test.ts: test that migration 4 adds the three columns and is idempotent.cli/src/core/event-store.test.ts: test that upsert/get round-trips the new fields, and that COALESCE preserves existing values on re-upsert.cli/src/types.ts # TraceMetadata type cli/src/core/migrations.ts # v4 migration cli/src/core/event-store.ts # CRUD for new columns cli/src/core/git.ts # NEW — git resolution utility cli/src/core/git.test.ts # NEW — tests cli/src/adapters/claude-code/v1.ts # resolve git info at scan time cli/src/services/api.ts # sync payload packages/shared/src/api/v1/openapi.json # API spec packages/shared/src/api/v1/gen/types.gen.ts # regenerated api/convex/schema.ts # Convex traces table api/convex/lib/validators.ts # request validation api/convex/internal/sync.ts # internal mutation args + handler api/convex/services/traces.ts # service layer + response mapping
cd cli && bun test — all existing + new tests passsqlite3 ~/.traces/traces.db "SELECT id, git_remote_url, git_branch, git_ref FROM traces LIMIT 5" — should show git data for traces in git repostraces share --trace-id <id> --json — confirm the API accepts the new fields without errorcd api && bun test — Convex tests passGET /v1/traces/:externalId returns gitRemoteUrl, gitBranch, gitRef in the responseIf you need specific details from before exiting plan mode (like exact code snippets, error messages, or content you generated), read the full transcript at: /Users/andrew/.claude/projects/-Users-andrew-code-traces-traces/a8f01d3c-295f-4043-ae2a-417299a74100.jsonl
I'll start by reading all the key files I need to modify to understand the existing patterns.
Now I have a clear picture of all the files. Let me create the feature branch and start implementing.
Let me check for existing test patterns and the shared package generate command.
Good, I have a complete picture. Let me set up tracking and start implementing all the changes. I'll work through the layers bottom-up.
Now let me start implementing. I'll begin with the type changes and work up through the layers.
Now update the EventStore. I need to update the CREATE TABLE, upsertTrace, updateTrace, getTrace, and listTraces.
Now update upsertTrace:
Now update updateTrace:
Now update getTrace:
Now update listTraces:
Now integrate git resolution into the adapter. I need to add the import and call resolveGitInfoCached after setting directory on each trace.
Now I need to add the git resolution after trace creation in getTraces. There are two places traces are built: the history-based path and the fallback path.
Now the fallback path:
Update the API sync payload and related functions:
Now update syncTraceMetadata to send the new fields:
Now update the OpenAPI spec. I need to add the three fields to TraceCreateRequest, TraceUpsertRequest, and TraceDetail.
Now update TraceDetail - it's an allOf extension of TraceSummary:
Now regenerate the API types:
Now update the API backend. Start with validators:
Now update the Convex schema:
Now update the internal sync mutation. Add the three fields to traceInput and the handler:
Now update the upsertTrace handler to include the new fields in both the update and insert paths:
Now update the service layer - mapTraceDetail and the service functions:
Now update the service functions that call upsertTrace to pass through the git fields:
Now the upsertTrace service function:
Now the updateTrace service function:
Now let me rebuild the shared package so the types are available:
Now write the tests. First, the git utility test:
Now add the migration v4 test to the existing migrations test file:
Now add the git field round-trip test to the event-store test file:
Now let me run the CLI tests:
619 pass, 1 fail, 1 error. Let me check what failed:
The failure is in setup.test.ts (missing @clack/prompts module) - that's a pre-existing issue, not related to my changes. Let me verify by running just the tests for the files I changed:
All 34 tests pass across the 3 test files. Now let me run the API tests: