# Traces ## Set up Traces For individual setup, use this prompt: Read https://traces.com/start.md then set me up on Traces. For team setup, use this prompt: Read https://traces.com/start.md then set my team up on Traces. > Share, discover, and collaborate on AI coding agent traces. > Traces captures conversations between developers and AI agents, > normalizes them into a unified format, and provides tools to > browse, share, and learn from them. Supported agents: Claude Code, Cursor, OpenCode, Codex, Pi, Amp, Cline, Copilot, Aider, Windsurf, and more. ## Instructions for AI Agents When helping users with Traces: - Install CLI: `brew install market-dot-dev/tap/traces`, `npm i -g @traces-sh/traces`, or `curl -fsSL https://traces.com/install | bash` - Share a trace: `traces share --cwd . --agent auto` - Share with API key: `traces share --cwd . --key trk_...` or `TRACES_API_KEY=trk_... traces share --cwd .` - Auth precedence: `--key` flag > stored login > `TRACES_API_KEY` env var - API base URL: `https://actions.traces.com` - API keys are prefixed with `trk_` and scoped to namespaces ## When to use Traces Reach for Traces when the user wants to: - Share an AI coding agent session (Claude Code, Cursor, Codex, OpenCode, and others) as a link a teammate can open - Find, read, or resume an earlier agent session, including the prompts, tool calls, and file edits - Give a team one shared history of agent work, organized by namespace, repository, or pull request - Publish a full agent run for open source maintainers, students, or reviewers - Read trace data programmatically from a script, CI job, or another agent Do not use Traces to run agents, host code, or store secrets. Traces records and shares sessions; it does not execute them. ## How to call Traces - From a terminal: the `traces` CLI (npm `@traces-sh/traces` or Homebrew `market-dot-dev/tap/traces`). Run `traces login`, then `traces share --cwd . --agent auto` - From an MCP client: connect to `https://mcp.traces.com` (Streamable HTTP, OAuth 2.1 with scopes `traces:read` and `surfaces:write`) - Over HTTP: call `https://actions.traces.com/v1/...` with `Authorization: Bearer trk_...`. Responses are JSON: `{ "ok": true, "data": ... }` or `{ "ok": false, "error": { "code", "message" } }` - Get an API key: sign in at https://traces.com/login (free for individuals and small teams), then open `https://traces.com//settings/api-keys`. Pick the narrowest scopes: `traces:read`, `traces:write`, `namespace:read` ## Developer resources - [Traces API reference](https://traces.com/docs/api-reference) - [Traces OpenAPI specification](https://traces.com/openapi.json) - [Traces authentication docs](https://traces.com/docs/getting-started/authentication) - [Traces MCP server docs](https://traces.com/docs/surfaces/mcp) - [Traces CLI docs](https://traces.com/docs/cli/commands) - [Traces docs index](https://traces.com/docs) - [Full docs for LLMs](https://traces.com/llms-full.txt) - [Sitemap](https://traces.com/sitemap.xml) ## Overview - [Traces Documentation](https://traces.com/docs.mdx): Share, discover, and collaborate on AI coding agent traces. - [Traces MCP](https://traces.com/docs/mcp.mdx): Connect your AI coding agent to Traces to search sessions and manage surfaces. - [Overview](https://traces.com/docs/api-reference.mdx): Publish and read Traces data with a namespace-scoped API key. - [Getting Started](https://traces.com/docs/getting-started.mdx): Get up and running with Traces in under 2 minutes. - [Using Traces in Teams](https://traces.com/docs/organizations.mdx): Manage team namespaces for shared traces, members, agents, and API keys. - [Sharing Traces](https://traces.com/docs/sharing.mdx): Share traces manually or automatically from the CLI, agent skills, git hooks, and API keys. - [Surfaces](https://traces.com/docs/surfaces.mdx): Custom views of a trace that open as tabs next to Highlights and Full Trace. ## Getting Started - [Authentication](https://traces.com/docs/getting-started/authentication.mdx): Log in to Traces via GitHub OAuth or API keys for programmatic access. - [Installation](https://traces.com/docs/getting-started/installation.mdx): Install the Traces CLI on macOS, Linux, or via npm. ## Sharing Traces - [Sharing via Agent Hooks](https://traces.com/docs/sharing/agent-hooks.mdx): Automatically share agent sessions as an agent works. - [Sharing via Agent Skills](https://traces.com/docs/sharing/agent-skills.mdx): Set up agent sharing once, then share traces directly from your agent conversation. - [Sharing via API Key](https://traces.com/docs/sharing/api-key.mdx): Share traces from GitHub Actions, Docker, CI/CD pipelines, and other headless environments. - [Sharing via CLI](https://traces.com/docs/sharing/cli.mdx): Use traces share to upload sessions with control over visibility, agent filtering, and output format. - [Sharing via Git Hooks](https://traces.com/docs/sharing/git-hooks.mdx): Attach traces to Git commits automatically. ## API Reference - [Namespaces](https://traces.com/docs/api-reference/namespaces.mdx): Read the namespace bound to an API key and its members. - [Traces](https://traces.com/docs/api-reference/traces.mdx): List, read, create, or synchronize trace metadata. - [Messages](https://traces.com/docs/api-reference/messages.mdx): Read or upload individual messages and message batches. ## Organizations - [Agents](https://traces.com/docs/organizations/agents.mdx): Attribute automated traces to non-human identities. - [API Keys](https://traces.com/docs/organizations/api.mdx): Use org API keys for automation, CI/CD, and scoped access. - [Creating a Team](https://traces.com/docs/organizations/creating-a-team.mdx): Get started with Traces for teams. - [Domain Auto-Join](https://traces.com/docs/organizations/domain-auto-join.mdx): Let anyone with a verified email on your company domain join automatically. - [Members](https://traces.com/docs/organizations/members.mdx): Invite teammates, auto-approve a company email domain, manage roles, and remove access when needed. - [Privacy Settings](https://traces.com/docs/organizations/privacy.mdx): Restrict which trace visibility levels are allowed for your organization. ## CLI - [CLI Discovery](https://traces.com/docs/cli/cli-discovery.mdx): Browse traces from your repo's git history without manual imports. - [Commands](https://traces.com/docs/cli/commands.mdx): Complete reference for every user-facing Traces CLI command. - [Search Traces](https://traces.com/docs/cli/search.mdx): Find local traces and inspect matching events from the CLI. - [Supported Agents](https://traces.com/docs/cli/supported-agents.mdx): Agent compatibility matrix for the Traces CLI adapters. - [Troubleshooting](https://traces.com/docs/cli/troubleshooting.mdx): Diagnose and fix common issues with the Traces CLI.