The big picture
Three pieces cooperate:
- The
agent-traceCLI runs on each developer’s machine. Hooks record traces locally as you code with Cursor, Claude Code, or Codex CLI; a post-commit hook links traces to each commit and builds a deterministic per-line attribution ledger. Nothing leaves the machine on its own. (CLI concepts →) - TracesHub (this application) is the hosted remote and the collaboration layer: GitHub sign-in, organizations and projects, scoped access tokens, and the web views — analytics, per-line file blame, and conversations.
- GitHub provides identity (OAuth sign-in) and repo linkage (the TracesHub GitHub App), so a project maps 1:1 to a repository and the web views can render your code at the default branch’s HEAD.
The flow: you code → the CLI records → you commit → the ledger is built → you run agent-trace push → the traces land in your TracesHub project → anyone with access browses them in the app.
Deterministic, not guesswork
Attribution is built at commit time from per-line SHA-256 hashes. A line is AI-written (with a specific model and tool) or it has no attribution — there is no heuristic scoring, ever. That property is inherited from the CLI and carried through everything TracesHub shows: the analytics percentages, the per-line blame, and the coverage numbers are all reads of that ledger, never estimates. Details: Attribution ledger in the CLI docs.
Organizations and projects
- Organization — the top-level container. Signing in creates a personal org for you automatically; installing the GitHub App on a GitHub organization creates a matching TracesHub org. Members have a role (owner / admin / member) and a default traces-access level. See Teams & access.
- Project — one GitHub repository imported into an org. A project holds the hosted trace store for that repo, plus its settings: whether traces are enabled, who can access them, and its remote URL.
A project is addressed as <org>/<repo>, exactly like GitHub — in the app (/p/<org>/<repo>) and in the CLI remote URL.
What actually moves over the wire
When you run agent-trace push, the CLI ships four artifact families to your project’s trace store:
| Artifact | What it is |
|---|---|
| Traces | Structured records of each AI editing session — which tool, which model, what changed. |
| Ledgers | The per-commit, per-line attribution map (line hash → trace) built at commit time. |
| Commit links | The binding between a git commit SHA and its traces/ledger. |
| Conversations & summaries | The prompt and session transcript behind traces (content-addressed by SHA-256, so a transcript shared across traces uploads once), plus optional session-end summaries. |
How much detail ships is under your control — CLI config toggles and push flags decide whether full conversations, prompts and summaries, or attribution only go up. See Data & privacy and the CLI’s push / pull / sync reference.
Nothing is pushed automatically. Recording is continuous and local; syncing is always an explicit command (Remotes & sync).
The trace remote and the gateway
Each project exposes an HTTP remote at:
https://api.traceshub.com/at/<org>/<repo>The stock open-source CLI talks to it — there is no TracesHub-specific client, login command, or device flow. You authenticate with a TracesHub-minted token bound to the remote (agent-trace remote add … --token or --token-env).
Behind that URL sits TracesHub’s signed gateway. Per request it resolves the project, checks that traces are enabled, verifies your token’s scope and your effective access, enforces rate and body-size limits, and only then forwards to the trace store. Two practical consequences:
- A project-scoped token physically cannot touch any other project.
- If a project’s traces are disabled, pushes are rejected until an org owner or admin re-enables them.
Two checkouts, one project
The remote URL is the canonical project identity. Two teammates on different machines each run agent-trace remote add with the same URL (and their own tokens); their local data dirs differ, but they push into — and pull from — the same hosted store. After a pull (or sync), one teammate’s local agent-trace blame and agent-trace context resolve lines the other wrote. The web app is the third view onto the same store, with no local setup needed to look.
What the web app reads
The app renders two kinds of views:
- Trace-store views (Raw trace store) read the synced artifacts directly — counts and breakdowns across everything ever pushed, on any branch.
- Codebase views (Analytics and Files) join the trace store with your repository at the default branch’s HEAD, read via the GitHub App. That’s what makes “each model’s share of the codebase, right now” and per-line blame with conversations possible in the browser.
Self-hosting
The storage engine (agent-trace-service) and the CLI are standalone open source — a team can run its own remote without TracesHub. The hosted application layers GitHub-linked identity, orgs and access control, scoped tokens, and the web views on top. The CLI works identically against either; only the remote URL and token source differ.