Layer 01 · Glossary

Glossary

The vocabulary of Traces, in plain language. These terms appear throughout the domain model, architecture, and workflow pages; several ordinary words (agent, session, visibility) carry precise meanings here.

The recorded conversation

Trace: One recorded AI coding-agent session: the user's prompts, the agent's replies, its reasoning blocks, and the tool calls it made, in order. A trace has a stable public identifier (external ID) that stays valid across re-uploads, git notes, and URLs of the form /s/<id>. Traces also record which agent product and model produced them, the project directory and git branch they belong to, and optional links to related traces (subagent or resume relationships).
Message & Part: The server-side model of a trace's content. A message is one turn (user, assistant, or system); a part is one typed block inside it — text, reasoning ("thinking"), a tool call, a tool result, an error, and so on. This grouped shape is what uploaders send and what readers receive.
Event: The CLI-side model of the same content: a flat, append-only stream of typed records (user_message, agent_text, agent_thinking, tool_call, tool_result, error). Events match how agents write their session files line by line; the CLI converts events into messages and parts at the moment of upload.
Adapter: The CLI component that knows one agent product's storage format and location (JSONL files, SQLite databases, JSON threads) and parses it into events. There are fifteen-plus adapters — one per supported agent — behind a single interface, plus a background indexer that discovers new sessions without full re-scans.
Highlights: The curated default view of a trace: the substantive conversation with noise (redundant tool output, system chatter) filtered out. The full unfiltered view remains available as a separate page.
AI analysis: A background pass that reads a trace's conversation and derives a short title and a structured summary (status, steps, keywords, badges). It runs after uploads go quiet, never blocks the upload, and falls back to a deterministic heuristic when the language model is unavailable. Analysis output is stored apart from the trace record itself.

Accounts and access

User: A person (or an unauthenticated device) known to the platform. Users are created automatically on first login and carry almost no profile data of their own.
Identity: One login method attached to a user: a device identity (a UUID generated by the CLI), a GitHub identity, or a Google identity. One user can hold several; linking a device identity to a GitHub login is what merges a CLI-only account into a web account.
Namespace: The account scope that owns everything publishable. A namespace is either individual (one user's personal area, slug like a username) or an org (a team with members). Every trace belongs to exactly one namespace; every profile page and every permission decision is namespace-scoped. Also called an organization in the org case.
Membership & role: The binding of a user to a namespace with a role: admin (manage settings, members, keys, and any trace) or member (publish and manage their own traces).
Invite code: A shareable code that admits a user into an org namespace with a chosen role. Codes can expire, be revoked, be capped to a number of uses, or be bound to an email address.
Visibility: A trace's disclosure level. Private: namespace members only. Direct: anyone with the link, unlisted. Public: listed in the discover catalog and feeds. Namespaces can restrict which levels their traces may use.
Session (auth): A server-side record proving "this request is this user." Three kinds share one table: cookie sessions for the web app (180 days), device sessions for the CLI (no expiry), and short-lived access tokens (1 hour, parented to a cookie session) for live queries. Raw tokens are never stored — only their hashes — and revoking a parent session kills its children.
API key: A trk_-prefixed bearer token scoped to one namespace with explicit permission scopes (traces:write, traces:read, namespace:read). Intended for automation. Keys can be bound to an agent bot identity so uploaded traces are attributed to it.
Exchange code & OAuth state: Two short-lived handoff artifacts. OAuth state (10 minutes) carries a login attempt through the provider round trip and doubles as the CLI's polling handle. An exchange code (60 seconds, single use) lets the web app swap an OAuth result for session cookies on its own domain.

Agents — one word, three meanings

Agent (coding agent): Most often, an AI coding agent product — Claude Code, Cursor, Codex, pi, and so on — identified by an agent ID and parsed by a matching adapter. Every trace records which agent produced it.
Agent (bot identity): A named, namespace-owned non-human publisher (e.g. "Deploy Bot") with its own slug and avatar. Binding an API key to one attributes the key's uploaded traces to the bot instead of a human.
Agent (the assistant): The conversational assistant: a standalone service that answers questions about a team's traces by searching, listing, and quoting them. Its conversation state is stored as agent sessions with append-only entries, deliberately separate from the trace product entity.

Publishing pipeline vocabulary

Soft delete & republish: Unpublishing a trace marks it deleted but keeps the record (and its URL) so it can be republished to the same address. Message bodies are removed from the analytics store shortly after; re-uploading clears the marker and pushes fresh content.
Analysis outbox & debounce: Uploads signal "this trace needs (re)analysis" by writing one coalescing durable request per trace instead of invoking a job directly. A dispatcher drains due requests every second into a bounded background worker pool, and a quiet-period check defers the run until writes settle (10–30 seconds). The result: one analysis per burst of uploads, never zero, never dozens.
Publish watermark: A per-trace timestamp bumped on every (re)publish. Readers of the append-only analytics store ignore rows older than the watermark, so leftovers from a previous publish can never leak into the current one.
Scrubbing: Secret redaction applied to trace content on the CLI before upload, and again server-side on derived artifacts. The goal is that tokens, keys, and credentials in a terminal session never reach the platform.
Models registry: A synchronized copy of the models.dev catalog (providers, model IDs, capabilities, pricing) used to resolve a trace's raw model string into a display name. Refreshed daily by a scheduled job.

Integration vocabulary

Git notes (refs/notes/traces): The mechanism that ties traces to code. Git hooks installed by the CLI append traces:<external-id> lines to a dedicated git-notes ref on each commit; the notes travel with pushes and are read by the GitHub App to decorate pull requests with trace links.
Agent hooks & the active-sessions file: Lifecycle hooks the CLI installs into supported coding agents (session start, prompt submitted, agent done, session end). They record which sessions are live in a per-worktree JSON file inside the git dir, so the commit-time hooks know exactly which traces to attach without searching.
GitHub App & installation: A GitHub App installed on repositories (separate from OAuth login). On pull-request events it reads the repo's trace notes, resolves the referenced traces, and upserts a comment linking them. Installations and their repos are recorded server-side and can be linked to a namespace.
Namespace export: A bulk, admin-requested export of a namespace's traces (optionally filtered by date range and visibility) into a downloadable archive, optionally uploaded onward to a Hugging Face dataset through a namespace-level OAuth integration.
Data layer: The web app's server-only data access layer: every page read goes through it, it forwards the user's cookies to the API, and it owns the caching policy (per-request deduplication plus short cross-request caches for public data).
Analytics store (Tinybird): The columnar store (Tinybird, over ClickHouse) that owns message and part bodies, the mirrored trace display rows, and AI-analysis output. It is eventually consistent (a flush window of seconds) and read through named SQL endpoints called pipes; the primary database remains authoritative for anything permission- or freshness-critical.