{"id":50982787,"url":"https://github.com/graycodeai/trace","last_synced_at":"2026-07-05T01:01:23.342Z","repository":{"id":356458986,"uuid":"1227574330","full_name":"GrayCodeAI/trace","owner":"GrayCodeAI","description":"Git-native session capture for AI coding agents — rewind, resume, and audit every AI interaction","archived":false,"fork":false,"pushed_at":"2026-06-30T06:15:00.000Z","size":17725,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-30T08:13:32.697Z","etag":null,"topics":["ai","ai-agents","checkpoints","cli","code-review","developer-tools","devtools","git","go","observability","session-tracking"],"latest_commit_sha":null,"homepage":"https://github.com/GrayCodeAI/trace","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GrayCodeAI.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-02T21:49:59.000Z","updated_at":"2026-06-30T06:15:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"b31183dd-e3d0-4d6c-8228-82bbdd399f18","html_url":"https://github.com/GrayCodeAI/trace","commit_stats":null,"previous_names":["graycodeai/trace"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/GrayCodeAI/trace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrayCodeAI%2Ftrace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrayCodeAI%2Ftrace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrayCodeAI%2Ftrace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrayCodeAI%2Ftrace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GrayCodeAI","download_url":"https://codeload.github.com/GrayCodeAI/trace/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GrayCodeAI%2Ftrace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35140189,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","checkpoints","cli","code-review","developer-tools","devtools","git","go","observability","session-tracking"],"created_at":"2026-06-19T16:04:09.893Z","updated_at":"2026-07-05T01:01:23.323Z","avatar_url":"https://github.com/GrayCodeAI.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003eTrace\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cstrong\u003eGit-native session capture for AI coding agents\u003c/strong\u003e\n  \u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e \u0026bull;\n    \u003ca href=\"#how-it-works\"\u003eHow It Works\u003c/a\u003e \u0026bull;\n    \u003ca href=\"#commands\"\u003eCommands\u003c/a\u003e \u0026bull;\n    \u003ca href=\"#configuration\"\u003eConfiguration\u003c/a\u003e \u0026bull;\n    \u003ca href=\"CONTRIBUTING.md\"\u003eContributing\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n---\n\nTrace hooks into your Git workflow to capture AI agent sessions as you work. Sessions are indexed alongside commits, creating a searchable record of *how* code was written — not just *what* changed.\n\n## Ecosystem Boundaries\n\nTrace is a Hawk support engine. Keep the dependency edge one-way:\n\n- trace uses local-only types (trace/redaction event types are trace-scoped, not shared contracts)\n- do not import `hawk/internal/*`\n- do not import removed legacy path `hawk/shared/types`\n- do not import other engines (`eyrie`, `yaad`, `tok`, `sight`, `inspect`) — engines are peers, not dependencies\n\n### What you get\n\n| Capability | Description |\n|---|---|\n| **Understand why code changed** | Full prompt/response transcripts, files touched, token usage |\n| **Rewind instantly** | Go back to any checkpoint when an agent goes sideways |\n| **Fork \u0026 A/B** | Branch a new independent session from any checkpoint to explore alternatives |\n| **Resume seamlessly** | Pick up where you or a coworker left off on any branch |\n| **Cost attribution** | USD cost broken down per session and per tool from recorded token usage |\n| **Clean git history** | All session data lives on a separate branch — zero noise |\n| **Audit \u0026 compliance** | Searchable, versioned record of every AI interaction |\n\n### Supported Agents\n\n| Agent | Status |\n|---|---|\n| Claude Code | Fully supported |\n| Codex | Fully supported |\n| Gemini CLI | Fully supported |\n| OpenCode | Fully supported |\n| Cursor | Supported (rewind unavailable) |\n| Factory AI Droid | Fully supported |\n| Copilot CLI | Fully supported |\n\n---\n\n## Quick Start\n\nTrace is a **library**, not a standalone binary. Its full command tree is built by\n`cli.NewRootCmd()` and surfaced inside the **Hawk** CLI as `hawk trace ...` (Hawk is in\ndevelopment — no public install yet). There is no separate `trace` binary to install.\n\n**Contributors — build/test the library from source:**\n\n```bash\ngit clone https://github.com/GrayCodeAI/trace \u0026\u0026 cd trace\ngo build ./...\ngo test ./...\n```\n\nOnce Hawk is available, use the commands under `hawk trace`:\n\n```bash\n# Enable in your project\ncd your-project\nhawk trace enable\n\n# Check status\nhawk trace status\n```\n\nThat's it. Trace runs silently in the background via Git hooks.\n\n---\n\n## How It Works\n\n```\nYour Branch                    trace/checkpoints/v1\n     |                                  |\n     v                                  |\n[Base Commit]                           |\n     |                                  |\n     |  +--- Agent works ---+           |\n     |  |  Step 1           |           |\n     |  |  Step 2           |           |\n     |  |  Step 3           |           |\n     |  +-------------------+           |\n     |                                  |\n     v                                  v\n[Your Commit] ----------------------\u003e [Session Metadata]\n     |                           (transcript, prompts,\n     v                            files touched, tokens)\n```\n\n**Key principles:**\n\n- Zero commits on your active branch\n- Session data stored on `trace/checkpoints/v1` orphan branch\n- Checkpoints created automatically at each commit\n- Non-destructive rewind — restores files without altering history\n- Works on any branch (main, feature, etc.)\n\n---\n\n## Typical Workflow\n\n### 1. Enable\n\n```bash\ntrace enable                     # Interactive setup\ntrace enable --agent claude-code # Non-interactive\n```\n\n### 2. Work normally\n\nUse your AI agent as before. Trace captures everything in the background.\n\n```bash\ntrace status   # Check session anytime\n```\n\n### 3. Rewind if needed\n\n```bash\ntrace checkpoint rewind   # Select a checkpoint to restore\n```\n\n### 4. Resume on another branch\n\n```bash\ntrace session resume \u003cbranch\u003e   # Restore session metadata \u0026 continue\n```\n\n### 5. Disable (optional)\n\n```bash\ntrace disable   # Removes hooks, code untouched\n```\n\n---\n\n## Commands\n\n| Command | Description |\n|---|---|\n| `trace enable` | Enable Trace in your repository |\n| `trace disable` | Remove hooks from repository |\n| `trace status` | Show current session info |\n| `trace agent` | Add, remove, or list agent integrations |\n| `trace configure` | Update non-agent settings |\n| `trace checkpoint` | List, explain, rewind, search checkpoints |\n| `trace checkpoint rewind` | Rewind to a previous checkpoint |\n| `trace checkpoint explain` | Explain a session or checkpoint |\n| `trace fork` | Clone a checkpoint into a new independent session for A/B testing |\n| `trace annotate` | Attach a comment to a session or checkpoint |\n| `trace ci-init` | Configure Trace to auto-capture sessions in CI |\n| `trace session` | View and manage sessions |\n| `trace session resume` | Restore session on a branch |\n| `trace session attach` | Attach to a detached session |\n| `trace session export` | Export a session (JSON envelope or asciinema cast) |\n| `trace clean` | Clean up orphaned session data |\n| `trace doctor` | Diagnose and fix issues |\n| `trace login` | Authenticate with Trace |\n| `trace version` | Show CLI version |\n\nRun `trace \u003ccommand\u003e --help` for detailed usage.\n\n---\n\n## Configuration\n\nTrace stores config in `.trace/` at the repo root.\n\n### Project settings (`.trace/settings.json`)\n\nShared with the team, committed to git:\n\n```json\n{\n  \"enabled\": true,\n  \"strategy_options\": {\n    \"push_sessions\": true,\n    \"summarize\": { \"enabled\": true }\n  }\n}\n```\n\n### Local overrides (`.trace/settings.local.json`)\n\nPersonal, gitignored:\n\n```json\n{\n  \"log_level\": \"debug\"\n}\n```\n\n### All options\n\n| Option | Values | Description |\n|---|---|---|\n| `enabled` | `true` / `false` | Toggle Trace |\n| `log_level` | `debug`, `info`, `warn`, `error` | Logging verbosity |\n| `strategy_options.push_sessions` | `true` / `false` | Auto-push checkpoints on git push |\n| `strategy_options.checkpoint_remote` | `{\"provider\": \"github\", \"repo\": \"...\"}` | Push checkpoints to separate repo |\n| `strategy_options.summarize.enabled` | `true` / `false` | AI summaries at commit time |\n| `attribution.attribute_co_authored_by` | `true` / `false` | Append `Co-authored-by: \u003cagent\u003e` trailer (default on) |\n| `attribution.attribute_author` | `true` / `false` | Set the git author to the agent (default off) |\n| `attribution.attribute_committer` | `true` / `false` | Set the git committer to the agent (default off) |\n| `dirty_commits` | `true` / `false` | Auto-commit a dirty working tree before an agent session (default on; `--no-dirty-commits` to skip) |\n| `webhooks` | `{\"urls\": [\"...\"], \"events\": [\"...\"]}` | POST a JSON notification on session lifecycle events (default off) |\n| `telemetry` | `true` / `false` | Anonymous usage analytics |\n\n### Checkpoint Remote\n\nPush session data to a separate private repo:\n\n```bash\ntrace enable --checkpoint-remote github:myorg/checkpoints-private\n```\n\n---\n\n## Security \u0026 Privacy\n\n- Session transcripts live on `trace/checkpoints/v1` in your repo\n- Secrets are automatically redacted (API keys, tokens, credentials) — best-effort\n- Shadow branches used during sessions are local-only and never pushed\n- See [docs/security-and-privacy.md](docs/security-and-privacy.md) for details\n\n---\n\n## Troubleshooting\n\n| Issue | Fix |\n|---|---|\n| \"Not a git repository\" | `cd` into a git repo first |\n| \"Trace is disabled\" | `trace enable` |\n| \"No rewind points\" | Work with your agent, then commit |\n| Shadow branch conflict | `trace clean --force` |\n\n**Debug mode:**\n\n```bash\nTRACE_LOG_LEVEL=debug trace status\n```\n\n**Reset everything:**\n\n```bash\ntrace clean --all --force\n```\n\n**Accessibility:**\n\n```bash\nexport ACCESSIBLE=1   # Screen reader friendly mode\n```\n\n---\n\n## Development\n\n```bash\n# Prerequisites: mise (https://mise.jdx.dev/)\ngit clone https://github.com/GrayCodeAI/trace.git\ncd trace \u0026\u0026 mise install \u0026\u0026 mise trust\n\n# Build\nmise run build\n\n# Test\nmise run test          # Unit tests\nmise run test:ci       # Full suite (unit + integration)\n\n# Lint \u0026 format\nmise run fmt \u0026\u0026 mise run lint\n```\n\nSee [CLAUDE.md](CLAUDE.md) for architecture details.\n\n---\n\n## License\n\nMIT \u0026mdash; see [LICENSE](LICENSE)\n\n---\n\n\u003cp align=\"center\"\u003e\n  Built by \u003ca href=\"https://github.com/GrayCodeAI\"\u003eGrayCode AI\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraycodeai%2Ftrace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgraycodeai%2Ftrace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraycodeai%2Ftrace/lists"}