[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80626":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":15,"stars30d":16,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":17,"rankGlobal":9,"rankLanguage":9,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":9,"pushedAt":9,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":14,"starSnapshotCount":14,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},80626,"tracebase","ssreeni1\u002Ftracebase","ssreeni1","Secure local trace capture and inspection for Codex and Claude agent sessions.",null,"JavaScript",76,9,67,0,1,7,44.2,"MIT License",false,"main",true,[],"2026-06-12 04:01:29","# Tracebase\n\nSecure, local-first trace capture and inspection for Codex and Claude agent sessions.\n\n\u003Cp>\n  \u003Ca href=\"LICENSE\">\u003Cimg alt=\"License\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-3fb950?style=for-the-badge\">\u003C\u002Fa>\n  \u003Ca href=\"CONTRIBUTING.md\">\u003Cimg alt=\"Contributing\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fcontributing-guide-0969da?style=for-the-badge\">\u003C\u002Fa>\n  \u003Ca href=\"SECURITY.md\">\u003Cimg alt=\"Security\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fsecurity-policy-f778ba?style=for-the-badge\">\u003C\u002Fa>\n  \u003Ca href=\"TESTING.md\">\u003Cimg alt=\"Testing\" src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Ftesting-checklist-8957e5?style=for-the-badge\">\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp>\n  \u003Ca href=\"#-install\">Install\u003C\u002Fa> |\n  \u003Ca href=\"#-what-you-can-answer\">What You Can Answer\u003C\u002Fa> |\n  \u003Ca href=\"#-privacy-defaults\">Privacy\u003C\u002Fa> |\n  \u003Ca href=\"#-mcp\">MCP\u003C\u002Fa> |\n  \u003Ca href=\"#-development\">Development\u003C\u002Fa> |\n  \u003Ca href=\"#-license\">License\u003C\u002Fa>\n\u003C\u002Fp>\n\n![Tracebase dashboard demo](assets\u002Ftracebase-interface-demo.gif)\n\nTracebase imports local agent transcripts, encrypts raw events at rest, builds a searchable local index, and serves a localhost dashboard for debugging what happened in an agent run. It is designed for developer workstations: no network interception, no hidden reasoning capture, and no remote service required.\n\nMost LLM observability tools start from application SDKs, hosted gateways, or OpenTelemetry pipelines. Tracebase starts from the local coding-agent logs developers already have, then turns those runs into auditable engineering traces: what happened, what failed, what recovered, what got expensive, and what is safe to share.\n\n## ✨ At A Glance\n\n| Capability | What You Get |\n| --- | --- |\n| Local capture | Import Codex and Claude JSONL transcripts, poll for new events, or use wrappers\u002Fhooks for future runs. |\n| Private storage | Raw events are AES-256-GCM encrypted under `TRACE_HOME`; searchable metadata is redacted. |\n| Dashboard | Browse sessions, events, canonical traces\u002Fspans, summaries, and exports at `127.0.0.1`. |\n| Live intake | Opt-in local HTTP intake for custom events and Datadog LLMObs-style spans. |\n| Exports | Redacted zip bundles by default; raw exports require explicit local intent. |\n| Run intelligence | Analyze sessions for failures, resteers, context waste, repeated commands, redactions, token rollups, and run scorecards. |\n| Local integrations | CLI, CommonJS API, MCP, bootstrap instructions, shell wrappers, and launchd watcher support. |\n\n## 🔎 What You Can Answer\n\nTracebase makes agent work inspectable after the fact. Use it to answer:\n\n| Question | Tracebase Signal |\n| --- | --- |\n| Did the agent actually run tests? | Tool commands, exit status, test output summaries, and session scorecards. |\n| Where did the run get stuck? | Failure, loop, resteer, recovery, repeated-command, and context-waste annotations. |\n| How much did this run use? | Model, token, cache, and reasoning usage rollups when transcripts expose them. |\n| Which files or tools mattered? | Structured tool metadata, touched-file hints, canonical spans, and searchable events. |\n| Is this safe to share? | Redacted exports, incident packets, redaction counts, and explicit raw-export gates. |\n| Did one run improve on another? | `run-compare` quality, failure, waste, token, and risk deltas. |\n\nContext-waste detection is intentionally practical rather than mystical: it catches repeated searches, repeated commands, large outputs, and other patterns that burn context without clearly moving the task forward. Some expensive actions are still necessary, such as real UI automation or final release logs; the scorecard is meant to make that tradeoff visible.\n\n## ⚡ Install\n\n| Requirement | Version |\n| --- | --- |\n| Node.js | Node.js 24 or newer |\n| npm | Bundled with Node |\n\n```sh\nnpm install -g tracebase-local\ntracebase init\ntracebase import\ntracebase serve\n```\n\nOpen `http:\u002F\u002F127.0.0.1:18427`.\n\nThe npm package is `tracebase-local`; it installs `tracebase`, `traces`, `tcodex`, and `tclaude`.\n\n## 📥 What It Captures\n\n| Source | Included |\n| --- | --- |\n| Codex transcripts | Existing JSONL sessions from `~\u002F.codex\u002Fsessions\u002F**\u002F*.jsonl`. |\n| Claude Code transcripts | Existing JSONL sessions from `~\u002F.claude\u002Fprojects\u002F**\u002F*.jsonl`. |\n| Claude hooks | Prompt\u002Ftool\u002Fsession lifecycle payloads when configured, recorded under the `claude` provider. |\n| Wrappers | Invocation start\u002Fend metadata for `tcodex` and `tclaude`. |\n| Live intake | Explicit POSTed events and spans when `tracebase agent` is running. |\n\nTracebase records transcript-visible prompts, assistant messages, exposed reasoning summaries, tool calls, tool results, cwd, timestamps, approvals\u002Ferrors when present, and raw provider transcript events. It does not capture hidden\u002Fprivate model chain-of-thought unless a provider explicitly emits that data.\n\n## 🔐 Privacy Defaults\n\n| Boundary | Default |\n| --- | --- |\n| Store location | `~\u002F.traces`, override with `TRACE_HOME=\u002Fpath\u002Fto\u002Fstore`. |\n| Raw data | Encrypted locally with a generated key file. |\n| Dashboard bind | `127.0.0.1`; remote bind requires `--allow-remote`. |\n| Intake | Disabled in `tracebase serve`; enabled by `tracebase agent` or `--allow-intake`. |\n| Raw blob API | Disabled unless `TRACEBASE_ALLOW_RAW_BLOB_API=1`. |\n| Raw HTTP export | Requires `x-tracebase-raw-export: 1`. |\n| Hidden reasoning | Not captured by design. |\n\nTo delete local Tracebase data:\n\n```sh\ntracebase watch-uninstall\nrm -rf ~\u002F.traces\n```\n\nSet `TRACE_KEY` to a base64-encoded 32-byte key only when you need to manage encryption externally.\n\n## 🧭 Quick Workflows\n\n| Goal | Commands |\n| --- | --- |\n| Backfill and browse | `tracebase import` then `tracebase serve` |\n| Print Codex bootstrap instructions | `tracebase bootstrap --agent codex` |\n| Print Claude bootstrap instructions | `tracebase bootstrap --agent claude` |\n| Write agent instructions | `tracebase install-instructions --agent codex --target .\u002FTRACEBASE_AGENT.md` |\n| Always-on macOS capture | `tracebase watch-install` then `tracebase watch-status` |\n| Live local intake | `tracebase agent --port 18427` |\n| Check capture health | `tracebase health` and `tracebase doctor` |\n| Export a redacted bundle | `tracebase export --session-id ID --out trace.zip` |\n| Pipe an export intentionally | `tracebase export --session-id ID --stdout > trace.zip` |\n| Export raw local data | `tracebase export --session-id ID --raw --out trace-raw.zip` |\n| Export a safe incident packet | `tracebase export --session-id ID --incident --out trace-incident.zip` |\n| Inspect token rollups | `tracebase analyze` then open the dashboard or `GET \u002Fapi\u002Fsession-metrics` |\n| Compare analyzed runs | `tracebase run-compare --base-session-id A --target-session-id B` |\n| Generate a local summary | `tracebase summarize --session-id ID --runner codex` |\n| Start MCP | `tracebase mcp` |\n\n## 🛠️ CLI Overview\n\n| Area | Commands |\n| --- | --- |\n| Setup | `init`, `bootstrap`, `install-instructions`, `shell-init`, `doctor` |\n| Capture | `import`, `import-file`, `watch`, `watch-install`, `watch-status`, `watch-uninstall`, `hook`, `install-claude-hooks` |\n| Inspect | `stats`, `health`, `recent`, `search`, `show`, `decision-log`, `trace-diff`, `run-compare`, `traces-list`, `spans` |\n| Dashboard\u002FAPI | `serve`, `agent` |\n| Export\u002Fsummary | `export`, `summarize` |\n| Observability | `analyze`, `llmobs-spans`, `llmobs-trace`, `net-snapshot` |\n| MCP | `mcp` |\n\n`tracebase doctor` reports paths, capture coverage, watcher state, and Codex\u002FClaude CLI availability. Run `tracebase --help` for full options.\n\n## Additional CLI Utilities 🧰\n\n| Utility | Purpose |\n| --- | --- |\n| `traces search \u003Cquery>` | Print matching indexed trace events as JSONL. |\n| `traces show \u003CblobId>` | Decrypt and print one raw local event. |\n| `traces hook-config` | Print Claude Code settings JSON for trace hooks. |\n| `traces shell-init` | Print shell aliases for this checkout. |\n\n## 🖥️ Dashboard and API\n\n`tracebase serve` runs a read-only localhost dashboard. `tracebase agent` serves the same UI with local intake enabled.\n\n| Endpoint | Purpose |\n| --- | --- |\n| `GET \u002Fapi\u002Fhealth` | Capture health, event counts, and intake state. |\n| `GET \u002Fapi\u002Fsessions` | Filtered session list. |\n| `GET \u002Fapi\u002Fevents` | Redacted indexed event search. |\n| `GET \u002Fapi\u002Ftraces`, `GET \u002Fapi\u002Fspans` | Canonical trace\u002Fspan projection. |\n| `GET \u002Fapi\u002Fllmobs\u002Ftraces`, `GET \u002Fapi\u002Fllmobs\u002Fspans` | Datadog LLMObs-compatible envelopes. |\n| `POST \u002Fapi\u002Fevents`, `POST \u002Fapi\u002Fspans`, `POST \u002Fapi\u002Fintake` | Opt-in live intake. |\n| `GET \u002Fapi\u002Fexport` | Redacted or explicitly raw zip export. |\n| `GET \u002Fapi\u002Fsession-metrics` | Analyzed token and run scorecard rollups. |\n| `GET \u002Fapi\u002Ftrace-diff` | Compare a session source transcript against indexed rows. |\n| `GET \u002Fapi\u002Frun-compare` | Compare analyzed scorecards for two sessions. |\n| `GET\u002FPOST \u002Fapi\u002Fsummaries\u002Fsession\u002F:id` | Cached or generated local session summaries. |\n\nState-changing browser requests reject `Origin` headers that do not exactly match the Tracebase server origin. CLI and curl requests without an `Origin` header remain supported.\nFor summaries, browser-supplied command overrides are ignored; the local server invokes only allowlisted `codex` or `claude` runners.\n\n## Programmatic API 🧩\n\n```js\nconst {\n  TraceStore,\n  buildExportZip,\n  createServer,\n  redactText\n} = require(\"tracebase-local\");\n\nconst store = new TraceStore();\nstore.init();\nconsole.log(store.healthStats());\n```\n\nThe package exports storage, server, export, summary, redaction, normalization, LLMObs, and MCP helpers.\n\n## 🔌 MCP\n\n```toml\n[mcp_servers.tracebase]\ncommand = \"node\"\nargs = [\"\u002Fabsolute\u002Fpath\u002Fto\u002Fbin\u002Ftraces.js\", \"mcp\"]\n```\n\nThe MCP server is read-only and exposes trace search plus canonical trace\u002Fspan listing. It intentionally does not expose write tools in the OSS build.\n\n## 🧪 Development\n\n```sh\nnpm install\nnpm test\nnpm audit --omit=dev\n```\n\nFor the full local checklist, see [TESTING.md](TESTING.md).\n\n| Command | Purpose |\n| --- | --- |\n| `npm run check` | Syntax check packaged JS. |\n| `npm run audit:release` | Release invariant audit. |\n| `npm run smoke` | Core CLI\u002FAPI\u002Fstorage smoke tests. |\n| `npm run test:stress` | Concurrent write and index rebuild stress test. |\n| `npm run test:ui` | Build dashboard and smoke served UI\u002FAPI. |\n| `npm run test:e2e-local` | Fixture-backed dashboard\u002Fexport\u002Fintake E2E. |\n| `npm run test:e2e-release` | Release-grade E2E for privacy, MCP, exports, comparison, intake, and rendered UI. |\n| `npm run test:package` | `npm pack --dry-run`. |\n| `npm run test:install` | Install the packed package in a temp project and verify CLI\u002FAPI behavior. |\n\n## 📚 Repository Docs\n\n| File | Purpose |\n| --- | --- |\n| [ARCHITECTURE.md](ARCHITECTURE.md) | Storage, ingestion, API, and security boundaries. |\n| [SECURITY.md](SECURITY.md) | Security model, issue guidance, and release checklist. |\n| [TESTING.md](TESTING.md) | Manual and automated validation workflows. |\n| [CONTRIBUTING.md](CONTRIBUTING.md) | Local development standards. |\n| [NOTICE.md](NOTICE.md) | Third-party notice summary. |\n\n## 📄 License\n\nMIT. See [LICENSE](LICENSE).\n","Tracebase 是一个用于安全地本地捕获和检查 Codex 和 Claude 代理会话的工具。其核心功能包括本地捕获、加密存储、以及提供一个本地可访问的仪表盘来帮助开发者调试代理运行过程中发生的情况。技术上，它使用 AES-256-GCM 加密保护数据隐私，并支持通过 CLI 或 CommonJS API 进行集成。此外，Tracebase 还具备实时事件摄入、智能分析会话失败原因及资源消耗情况等功能。适用于开发人员在工作站上进行本地开发与调试时，希望对 AI 代理的行为有更深入理解的场景。",2,"2026-06-11 04:01:25","CREATED_QUERY"]