Workflow · Code integration

Link traces to pull requests

Reviewers see the code a pull request changes — but not the conversation that produced it. This workflow attaches trace references to commits as they are made, so every pull request can carry links to the exact agent sessions behind it, with no manual step after a one-time setup.

Goal, trigger, and result

Goal: make "which traces produced this code?" answerable from the pull request itself. Trigger: committing and pushing in a repository where the integration is installed, then opening or updating a pull request. What enters: the developer's local session activity and the repository's commit events. What leaves: a self-updating comment on the pull request linking the relevant traces, plus durable git notes that travel with the repository.

Part one: from agent session to annotated commit

Two layers of hooks cooperate. Hooks inside the coding agent notice when sessions start, when prompts are submitted, and when the agent finishes, and they record the live sessions in a small per-worktree file — and share the in-progress trace in the background. Hooks inside git then fire at commit time: one collects the active trace references, and one writes them into the repository's notes and pushes them. Everything after the commit itself happens in the background, so committing is never slowed down or blocked.

sequenceDiagram
  autonumber
  actor Dev as Developer
  participant Agent as Coding agent
  participant Hooks as Installed hooks
  participant Git as Git repository
  participant CLI as Command-line tool
  participant API as Platform API

  Dev->>Agent: works on a change
  Agent->>Hooks: lifecycle events (start · prompt · done · end)
  Hooks->>Git: record live sessions in the worktree's active file
  Hooks->>CLI: share the in-progress trace (background)
  CLI->>API: upload / refresh the trace
  Dev->>Git: commit
  Git->>Hooks: commit-time hooks fire
  Hooks->>Git: read the active file · attach trace references as notes on the commit
  Hooks->>CLI: share anything unshared (background, never blocks)
  Hooks->>Git: push the notes to the remote (retried on next push if offline)
  Note over Hooks: persistent failures (e.g. logged out) surface
as a warning at the next commit or push

The notes are appended, not overwritten, so several developers — and several sessions — can each attach their traces to the same commit. Because notes are ordinary git refs, they clone and fetch like any other history: a teammate who clones the repo can immediately browse every trace attached to its past commits.

Part two: from pushed notes to a pull-request comment

On the hosting side, the platform's GitHub App receives pull-request events for repositories where it is installed. It reads the notes straight from the repository — no extra sync step — resolves each referenced trace, and keeps one comment up to date as the branch grows.

sequenceDiagram
  autonumber
  actor Rev as Reviewer
  participant GH as GitHub
  participant Hook as Platform webhook
  participant API as Platform API
  participant Store as Metadata store

  Note over GH: pull request opened or updated
  GH->>Hook: signed pull-request event
  Hook->>Hook: verify the signature · queue processing
  Hook->>GH: authenticate as the app installation
  Hook->>GH: list the pull request's commits
  Hook->>GH: read the trace notes on those commits
  GH-->>Hook: trace references
  Hook->>API: resolve each referenced trace
  API->>Store: load trace records (title · author · agent · size)
  Store-->>Hook: traces on the pull request's branch
  Hook->>GH: create or update the pull-request comment with trace links
  Rev->>GH: opens the pull request
  GH-->>Rev: code plus links to the conversations that produced it
  Rev->>API: follows a trace link
  API-->>Rev: the trace page (subject to its visibility)

Two details keep the comment honest. Traces are filtered by branch, so notes that land on commits through rebases or shared history don't pull unrelated sessions into the pull request. And the comment is a single upserted marker, so force-pushes and new commits rewrite it rather than stacking up duplicates. Traces keep their normal visibility rules — a link in a comment never makes a private trace readable to outsiders.