{"id":34706670,"url":"https://github.com/lanegrid/agtrace","last_synced_at":"2026-01-07T12:12:03.096Z","repository":{"id":330343322,"uuid":"1108376488","full_name":"lanegrid/agtrace","owner":"lanegrid","description":"The Observability Platform for AI Agents.","archived":false,"fork":false,"pushed_at":"2026-01-01T04:45:25.000Z","size":7646,"stargazers_count":3,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-01T07:23:29.694Z","etag":null,"topics":["ai","claude-code","codex","coding-agent","gemini-cli","observability"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lanegrid.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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":"2025-12-02T11:22:16.000Z","updated_at":"2026-01-01T07:16:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lanegrid/agtrace","commit_stats":null,"previous_names":["lanegrid/agtrace"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/lanegrid/agtrace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanegrid%2Fagtrace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanegrid%2Fagtrace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanegrid%2Fagtrace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanegrid%2Fagtrace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lanegrid","download_url":"https://codeload.github.com/lanegrid/agtrace/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanegrid%2Fagtrace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28173971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2026-01-02T02:00:06.235Z","response_time":54,"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","claude-code","codex","coding-agent","gemini-cli","observability"],"created_at":"2025-12-24T23:28:02.636Z","updated_at":"2026-01-02T16:13:57.876Z","avatar_url":"https://github.com/lanegrid.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/lanegrid/agtrace/main/docs/images/agtrace-icon.png\" width=\"96\" alt=\"agtrace logo\"\u003e\n  \u003ch1\u003eagtrace\u003c/h1\u003e\n  \u003cp\u003e\u003cstrong\u003eThe Observability Platform for AI Agents.\u003c/strong\u003e\u003c/p\u003e\n  \u003cp\u003eLocal-first OpenTelemetry for Claude, Codex, and Gemini.\u003c/p\u003e\n\n  [![npm](https://img.shields.io/npm/v/@lanegrid/agtrace.svg?style=flat\u0026label=npm)](https://www.npmjs.com/package/@lanegrid/agtrace)\n  [![crates.io](https://img.shields.io/crates/v/agtrace-sdk.svg?label=SDK)](https://crates.io/crates/agtrace-sdk)\n\u003c/div\u003e\n\n---\n\n![agtrace watch demo](https://raw.githubusercontent.com/lanegrid/agtrace/main/docs/assets/demo.gif)\n\n**agtrace** provides a unified timeline and analysis layer for fragmented AI agent logs.\nUse the **CLI** for instant visualization, or build custom monitoring tools with the **SDK**.\n\n## 🌟 Core Value\n\n1. **Universal Normalization**: Converts diverse provider logs (Claude, Gemini, etc.) into a standard `AgentEvent` model.\n2. **Schema-on-Read**: Resilient to provider updates. No database migrations needed.\n3. **Local-First**: 100% offline. Privacy by design.\n4. **Zero-Instrumentation**: Automatically detects and watches logs from standard locations (`~/.claude/projects`, `~/.codex/sessions`, `~/.gemini/tmp`). No code changes required.\n\n## 🚀 Quick Start (CLI)\n\nThe reference implementation of the agtrace platform.\n\n```bash\nnpm install -g @lanegrid/agtrace\ncd my-project\nagtrace init      # initialize workspace (system data directory)\nagtrace watch     # live dashboard\n```\n\n## 🤖 AI-Native Observability (MCP)\n\n**New in v0.4.0**: Enable AI agents to query their own execution history.\n\nagtrace exposes a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that allows AI assistants like Claude Desktop to:\n- Browse session history and analyze failures\n- Search event payloads across thousands of sessions\n- Run diagnostic analysis (failures, loops, bottlenecks)\n- Debug agent behavior without manual CLI commands\n\n### Setup with Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"agtrace\": {\n      \"command\": \"agtrace\",\n      \"args\": [\"mcp\", \"serve\"]\n    }\n  }\n}\n```\n\n**Troubleshooting**: If you use a Node.js version manager (mise, nvm, asdf, volta), Claude Desktop may not find `node` in its PATH. Use the explicit Node.js path instead:\n\n```bash\n# Find your Node.js and agtrace paths\nwhich node\nnpm root -g\n```\n\nThen configure with explicit paths:\n\n```json\n{\n  \"mcpServers\": {\n    \"agtrace\": {\n      \"command\": \"/path/to/node\",\n      \"args\": [\n        \"/path/to/global/node_modules/@lanegrid/agtrace/run-agtrace.js\",\n        \"mcp\",\n        \"serve\"\n      ]\n    }\n  }\n}\n```\n\nAfter restarting Claude Desktop, ask questions like:\n- *\"Show me sessions from the last 2 hours that had failures\"*\n- *\"Search for all tool calls containing 'write_file'\"*\n- *\"Analyze the most recent session for performance issues\"*\n\n### Available MCP Tools\n\n- `list_sessions` - Browse session history with filtering\n- `get_session_details` - Get session overview, turns, or full details\n- `analyze_session` - Run diagnostic analysis (failures, loops)\n- `search_events` - Search event payloads across sessions\n- `get_project_info` - List all indexed projects\n\n**See also**: Run `agtrace mcp serve --help` for details.\n\n## 🛠️ Building with the SDK\n\nEmbed agent observability into your own tools (vital-checkers, IDE plugins, dashboards).\n\n```toml\n[dependencies]\nagtrace-sdk = \"0.3\"\n```\n\n```rust,no_run\nuse agtrace_sdk::{Client, Lens, types::SessionFilter};\n\nlet client = Client::connect_default().await?;\nlet sessions = client.sessions().list(SessionFilter::all())?;\nif let Some(summary) = sessions.first() {\n    let handle = client.sessions().get(\u0026summary.id)?;\n    let report = handle.analyze()?.through(Lens::Failures).report()?;\n    println!(\"Health: {}/100\", report.score);\n}\n```\n\n**See also**: [SDK Documentation](https://docs.rs/agtrace-sdk) | [Examples](crates/agtrace-sdk/examples/) | [SDK README](crates/agtrace-sdk/README.md)\n\n## 📚 Documentation\n\n- [Why agtrace?](docs/motivation.md) - Understanding the problem and solution\n- [Getting Started](docs/getting-started.md) - Detailed installation and usage guide\n- [Architecture](docs/architecture.md) - Platform design and principles\n- [SDK Documentation](crates/agtrace-sdk/README.md) - Building custom tools\n- [Full Documentation](docs/README.md) - Commands, FAQs, and more\n\n## 🔌 Supported Providers\n\n- **Claude Code** (Anthropic)\n- **Codex** (OpenAI)\n- **Gemini** (Google)\n\n## 📦 Architecture\n\n```mermaid\ngraph TD\n    CLI[agtrace-cli] --\u003e SDK[agtrace-sdk]\n    YourApp[Your Tool] --\u003e SDK\n    SDK --\u003e Core[Core Engine \u0026 Providers]\n```\n\n- **Core SDK**: `agtrace-sdk`, `agtrace-engine`, `agtrace-providers`\n- **Applications**: `agtrace-cli` (Reference Implementation)\n\n## License\n\nDual-licensed under the MIT and Apache 2.0 licenses.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanegrid%2Fagtrace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flanegrid%2Fagtrace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanegrid%2Fagtrace/lists"}