# 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://www.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

## Overview
- [Traces Documentation](https://www.traces.com/docs.mdx): Share, discover, and collaborate on AI coding agent traces.
- [Getting Started](https://www.traces.com/docs/getting-started.mdx): Get up and running with Traces in under 2 minutes.
- [Organizations](https://www.traces.com/docs/organizations.mdx): Manage team namespaces for shared traces, members, agents, and API keys.
- [Sharing Traces](https://www.traces.com/docs/sharing.mdx): Share traces manually or automatically from the CLI, agent skills, git hooks, and API keys.

## Getting Started
- [Authentication](https://www.traces.com/docs/getting-started/authentication.mdx): Log in to Traces via GitHub OAuth or API keys for programmatic access.
- [Installation](https://www.traces.com/docs/getting-started/installation.mdx): Install the Traces CLI on macOS, Linux, or via npm.
- [Teams](https://www.traces.com/docs/getting-started/teams.mdx): Get started with Traces for teams.

## Sharing Traces
- [Sharing via Agent Skills](https://www.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://www.traces.com/docs/sharing/api-key.mdx): Share traces from GitHub Actions, Docker, CI/CD pipelines, and other headless environments.
- [Sharing via CLI](https://www.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://www.traces.com/docs/sharing/git-hooks.mdx): Attach trace IDs to git commits automatically with a post-commit hook.

## Organizations
- [Agents](https://www.traces.com/docs/organizations/agents.mdx): Attribute automated traces to non-human identities.
- [API Keys](https://www.traces.com/docs/organizations/api.mdx): Use org API keys for automation, CI/CD, and scoped access.
- [Members](https://www.traces.com/docs/organizations/members.mdx): Invite teammates, manage roles, and remove access when needed.
- [Privacy Settings](https://www.traces.com/docs/organizations/privacy.mdx): Restrict which trace visibility levels are allowed for your organization.

## CLI
- [CLI Discovery](https://www.traces.com/docs/cli/cli-discovery.mdx): Browse traces from your repo's git history without manual imports.
- [Commands](https://www.traces.com/docs/cli/commands.mdx): Complete reference for every user-facing Traces CLI command.
- [Search Traces](https://www.traces.com/docs/cli/search.mdx): Find local traces and inspect matching events from the CLI.
- [Supported Agents](https://www.traces.com/docs/cli/supported-agents.mdx): Agent compatibility matrix for the Traces CLI adapters.
- [Troubleshooting](https://www.traces.com/docs/cli/troubleshooting.mdx): Diagnose and fix common issues with the Traces CLI.