{"id":49871169,"url":"https://github.com/epsilla-cloud/clawtrace","last_synced_at":"2026-05-15T07:35:16.384Z","repository":{"id":350360619,"uuid":"1206515214","full_name":"epsilla-cloud/clawtrace","owner":"epsilla-cloud","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-10T02:01:30.000Z","size":176693,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-10T03:10:41.279Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/epsilla-cloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":null,"dco":null,"cla":null}},"created_at":"2026-04-10T01:51:17.000Z","updated_at":"2026-04-10T02:02:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/epsilla-cloud/clawtrace","commit_stats":null,"previous_names":["epsilla-cloud/clawtrace"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/epsilla-cloud/clawtrace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epsilla-cloud%2Fclawtrace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epsilla-cloud%2Fclawtrace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epsilla-cloud%2Fclawtrace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epsilla-cloud%2Fclawtrace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/epsilla-cloud","download_url":"https://codeload.github.com/epsilla-cloud/clawtrace/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epsilla-cloud%2Fclawtrace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33057995,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-15T02:00:06.351Z","response_time":103,"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":[],"created_at":"2026-05-15T07:35:12.082Z","updated_at":"2026-05-15T07:35:16.370Z","avatar_url":"https://github.com/epsilla-cloud.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"packages/clawtrace-ui/public/clawtrace-logo.png\" alt=\"ClawTrace\" width=\"260\" /\u003e\n\u003c/p\u003e\n\n\u003ch3 align=\"center\"\u003eCost-aware tracing \u0026amp; skill distillation for LLM agents\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://clawtrace.ai\"\u003eWebsite\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://clawtrace.ai/docs\"\u003eDocs\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://arxiv.org/abs/2604.23853\"\u003ePaper\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://clawtrace.ai/docs/ask-tracy\"\u003eAsk Tracy\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"#getting-started\"\u003eQuickstart\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://arxiv.org/abs/2604.23853\"\u003e\u003cimg src=\"https://img.shields.io/badge/arXiv-2604.23853-b31b1b?logo=arxiv\u0026logoColor=white\" alt=\"arXiv\" /\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache%202.0-blue\" alt=\"License\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/OpenClaw-compatible-orange\" alt=\"OpenClaw\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Next.js-15-black?logo=nextdotjs\" alt=\"Next.js\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/FastAPI-Python-009688?logo=fastapi\u0026logoColor=white\" alt=\"FastAPI\" /\u003e\n\u003c/p\u003e\n\n---\n\n## Paper\n\n\u003e **ClawTrace: Cost-Aware Tracing for LLM Agent Skill Distillation** \u0026nbsp;—\u0026nbsp;\n\u003e Boqin Yuan, Renchu Song, Yue Su, Sen Yang, Jing Qin · arXiv [2604.23853](https://arxiv.org/abs/2604.23853)\n\nSkill-distillation pipelines learn reusable rules from LLM agent trajectories, but they lack a key signal — **how much each step costs**. ClawTrace records every LLM call, tool use, and sub-agent spawn during a session and compiles it into a **TraceCard**: a ~1.5 kB YAML summary with per-step USD cost, token counts, and redundancy flags. On top of TraceCards, **CostCraft** produces three patch types — *preserve*, *prune* (with counterfactual evidence), and *repair* — that improve agent skills without inflating cost.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"packages/clawtrace-ui/public/docs/images/paper-workflow.png\" alt=\"ClawTrace + CostCraft workflow: capture, compile, distill\" width=\"860\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003csub\u003e\u003cb\u003eCapture → Compile → Distill.\u003c/b\u003e ClawTrace instruments the agent (Substrate), compiles each session into a TraceCard (IR), and merges TraceCards into evolved skills via a preserve / prune / repair typology (Methodology).\u003c/sub\u003e\u003c/p\u003e\n\n📄 **Read the paper:** \u003chttps://arxiv.org/abs/2604.23853\u003e \u0026nbsp;·\u0026nbsp; [BibTeX](#citation)\n\n---\n\n## Why this exists\n\nMy OpenClaw agent burned ~40× its normal token budget in under an hour. Root cause: it was appending ~1,500 messages of history to every LLM call. By the time I noticed, it had already spent a few dollars on what should have been a 3-cent task — and I couldn't see it from logs, because OpenClaw flattens everything into a wall of JSON. The loop was invisible.\n\nClawTrace was built after that incident, and the paper above is what came out of using it at scale.\n\n---\n\n**ClawTrace records every agent run as a tree of spans and lets you inspect it.**\n\n```bash\nopenclaw plugins install @epsilla/clawtrace\nopenclaw clawtrace setup\nopenclaw gateway restart\n```\n\nThen open [clawtrace.ai](https://clawtrace.ai). Your next run appears automatically.\n\n---\n\n## What it shows\n\n- **Token usage per step** — see exactly which LLM call ate your budget\n- **Tool calls and retries** — spot loops before they compound\n- **Execution timeline** — Gantt chart of every span, parallel and sequential\n- **Full input/output** — click any step to see what went in and what came back\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"packages/clawtrace-ui/public/docs/images/2.2.1-see-detail-trajectory---tracing-view.png\" alt=\"Trace tree view\" width=\"720\" /\u003e\n\u003c/p\u003e\n\n---\n\n## Ask Tracy\n\nYou can also ask questions in plain English. Tracy is an AI analyst wired directly to your trajectory graph. She runs live Cypher queries against your data, generates charts, and tells you specifically what to fix.\n\n\u003e \"Why did my last run cost so much?\"\n\u003e \"Which tool is failing most often?\"\n\u003e \"Is my context window growing across sessions?\"\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"packages/clawtrace-ui/public/docs/images/ask_tracy_4_result.png\" alt=\"Tracy analyzing trajectory costs\" width=\"600\" /\u003e\n\u003c/p\u003e\n\n---\n\n## Three views per trace\n\nEvery trajectory has three views — click any node/span/bar to open step detail with full payloads, token counts, duration, cost, and errors.\n\n**Execution path** — collapsible tree, parent-child relationships, per-node cost badges\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"packages/clawtrace-ui/public/docs/images/2.2.1-see-detail-trajectory---tracing-view.png\" alt=\"Execution Path\" width=\"720\" /\u003e\n\u003c/p\u003e\n\n**Call graph** — force-directed diagram of every agent, model, and tool in the run\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"packages/clawtrace-ui/public/docs/images/2.2.1-see-detail-trajectory---graph-view.png\" alt=\"Call Graph\" width=\"720\" /\u003e\n\u003c/p\u003e\n\n**Timeline** — Gantt chart showing where time actually went\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"packages/clawtrace-ui/public/docs/images/2.2.3-see-detail-trajectory---timeline-view.png\" alt=\"Timeline\" width=\"720\" /\u003e\n\u003c/p\u003e\n\n---\n\n## Getting started\n\n### 1. Install the plugin on your OpenClaw agent\n\n```bash\nopenclaw plugins install @epsilla/clawtrace\n```\n\n### 2. Authenticate\n\n```bash\nopenclaw clawtrace setup\n```\n\nPaste your observe key from [clawtrace.ai](https://clawtrace.ai) when prompted. 200 free credits, no credit card.\n\n### 3. Restart the gateway\n\n```bash\nopenclaw gateway restart\n```\n\nDone. Every run now streams to ClawTrace automatically.\n\n---\n\n## Self-evolving agents\n\nThe plugin also exposes a `/v1/evolve/ask` endpoint so your agent can query Tracy about its own trajectories. Install the ClawTrace Self-Evolve skill and your agent will periodically check its own cost and failure patterns, apply fixes, and log what it changed.\n\n```bash\nopenclaw skills install clawtrace-self-evolve\n```\n\n---\n\n## Architecture\n\n```mermaid\ngraph TB\n    subgraph Agent Runtime\n        OC[OpenClaw Agent]\n        PLG[\"@epsilla/clawtrace plugin\u003cbr/\u003e8 hook types\"]\n    end\n\n    subgraph Ingest Layer\n        ING[Ingest Service\u003cbr/\u003eFastAPI + Cloud Storage]\n    end\n\n    subgraph Data Lake\n        RAW[Raw JSON Events\u003cbr/\u003eAzure Blob / GCS / S3]\n        DBX[Databricks Lakeflow\u003cbr/\u003eSQL Pipeline]\n        ICE[Iceberg Silver Tables\u003cbr/\u003eevents_all, pg_traces,\u003cbr/\u003epg_spans, pg_agents]\n    end\n\n    subgraph Graph Layer\n        PG[PuppyGraph\u003cbr/\u003eCypher over Delta Lake]\n    end\n\n    subgraph Backend Services\n        API[Backend API\u003cbr/\u003eFastAPI + asyncpg]\n        PAY[Payment Service\u003cbr/\u003eCredits + Stripe]\n        MCP[Tracy MCP Server\u003cbr/\u003eCypher queries]\n    end\n\n    subgraph AI Layer\n        TRACY[Tracy Agent\u003cbr/\u003eAnthropic Managed Harness\u003cbr/\u003eClaude Sonnet 4.6]\n    end\n\n    subgraph Frontend\n        UI[ClawTrace UI\u003cbr/\u003eNext.js 15 + React 19]\n        DOCS[Documentation\u003cbr/\u003eServer-rendered Markdown]\n    end\n\n    subgraph External\n        NEON[(Neon PostgreSQL\u003cbr/\u003eUsers, API Keys,\u003cbr/\u003eCredits, Sessions)]\n        STRIPE[Stripe\u003cbr/\u003ePayments]\n    end\n\n    OC --\u003e PLG\n    PLG --\u003e|\"POST /v1/traces/events\"| ING\n    ING --\u003e RAW\n    RAW --\u003e DBX\n    DBX --\u003e ICE\n    ICE --\u003e PG\n\n    PG --\u003e|Cypher| API\n    PG --\u003e|Cypher| MCP\n\n    API --\u003e NEON\n    PAY --\u003e NEON\n    PAY --\u003e STRIPE\n\n    MCP --\u003e|tool results| TRACY\n    TRACY --\u003e|SSE stream| API\n\n    UI --\u003e|REST API| API\n    UI --\u003e|SSE| API\n    API --\u003e|deficit check| PAY\n```\n\n### Data flow\n\n1. **Capture** — The plugin intercepts 8 OpenClaw hook types: `session_start`, `session_end`, `llm_input`, `llm_output`, `before_tool_call`, `after_tool_call`, `subagent_spawning`, `subagent_ended`\n2. **Ingest** — Events are batched and POSTed to the ingest service, which writes partitioned JSON to cloud storage (`tenant={id}/agent={id}/dt=YYYY-MM-DD/hr=HH/`)\n3. **Transform** — Databricks Lakeflow SQL pipeline materializes raw events into 8 Iceberg silver tables every 3 minutes\n4. **Query** — PuppyGraph virtualizes the Delta Lake tables as a Cypher-queryable graph (Tenant → Agent → Trace → Span with CHILD_OF edges)\n5. **Serve** — Backend API runs Cypher queries; Tracy's MCP server gives the AI analyst direct graph access\n6. **Display** — Next.js UI renders trace trees, call graphs, timelines, and Tracy's streamed responses with inline ECharts\n\n### Graph schema\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"packages/clawtrace-ui/public/docs/images/graph_schema.png\" alt=\"PuppyGraph Schema: Tenant → Agent → Trace → Span\" width=\"720\" /\u003e\n\u003c/p\u003e\n\n4 vertex types (Tenant, Agent, Trace, Span), 4 edge types (HAS_AGENT, OWNS, HAS_SPAN, CHILD_OF). Agent execution data is naturally a graph; ClawTrace models it that way so Tracy can traverse it with Cypher instead of joining flat tables.\n\n### Monorepo structure\n\n```\nclawtrace/\n├── packages/clawtrace-ui/        Next.js 15 frontend (App Router, React 19, Drizzle ORM)\n├── services/clawtrace-backend/   FastAPI backend (PuppyGraph, JWT auth, Tracy chat)\n├── services/clawtrace-ingest/    FastAPI ingest (multi-tenant, cloud-agnostic storage)\n├── services/clawtrace-payment/   FastAPI billing (consumption credits, Stripe, notifications)\n├── plugins/clawtrace/            @epsilla/clawtrace npm plugin for OpenClaw\n├── sql/databricks/               Lakeflow SQL pipeline (silver tables + billing tables)\n└── puppygraph/                   PuppyGraph schema configuration\n```\n\n### Tech stack\n\n| Layer | Technology |\n|-------|-----------|\n| Frontend | Next.js 15, React 19, CSS Modules, ECharts, react-markdown |\n| Backend | FastAPI, asyncpg, httpx, Pydantic Settings |\n| Database | Neon PostgreSQL (users, credits, sessions), Drizzle ORM |\n| Data Lake | Azure Blob Storage, Databricks, Delta Lake, Iceberg |\n| Graph | PuppyGraph (Cypher over Delta Lake) |\n| AI | Anthropic Managed Agents (Claude Sonnet 4.6), MCP protocol |\n| Billing | Stripe, consumption-based credits |\n| Deployment | Vercel (UI), Docker + Kubernetes (services) |\n\n---\n\n## Model pricing\n\nCost estimates cover 80+ models with cache-aware pricing (fresh input, cached input, cache write, output calculated separately):\n\n**Western:** OpenAI (GPT-5.x, GPT-4.x, o-series), Anthropic (Claude Opus/Sonnet/Haiku), Google (Gemini 3.x/2.x/1.5), DeepSeek (V3, R1), Mistral\n\n**Chinese:** Alibaba Qwen (3.x Max/Plus/Flash), Zhipu GLM, Moonshot Kimi, Baidu ERNIE, MiniMax\n\n**Open source:** Llama 4/3.x, Mixtral, Stepfun\n\n---\n\n## Roadmap\n\n- **Rubric-based evaluation** — define quality rubrics, auto-score trajectories, catch regressions before deployment\n- **A/B testing** — run agent variants side by side, compare cost/quality/speed, promote winners\n- **Version control** — track agent config changes, roll back, audit\n- **Self-evolving agents** — agents that learn from their own trajectory data to cut costs and fix failure patterns automatically\n\n---\n\n## Development\n\n### Frontend\n\n```bash\ncd packages/clawtrace-ui\nnpm install\nnpm run dev          # localhost:3000\nnpm run typecheck\n```\n\n### Backend\n\n```bash\ncd services/clawtrace-backend\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -r requirements.txt\ncp .env.example .env\nuvicorn app.main:app --reload --port 8082\n```\n\n### Ingest\n\n```bash\ncd services/clawtrace-ingest\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -r requirements.txt\ncp .env.example .env\nuvicorn app.main:app --reload --port 8080\n```\n\n### Plugin\n\n```bash\ncd plugins/clawtrace\nnpm install\nnpm test\n```\n\n---\n\n## Citation\n\nIf you use ClawTrace, TraceCards, or CostCraft in academic work, please cite:\n\n```bibtex\n@article{yuan2026clawtrace,\n  title   = {ClawTrace: Cost-Aware Tracing for LLM Agent Skill Distillation},\n  author  = {Yuan, Boqin and Song, Renchu and Su, Yue and Yang, Sen and Qin, Jing},\n  journal = {arXiv preprint arXiv:2604.23853},\n  year    = {2026},\n  url     = {https://arxiv.org/abs/2604.23853}\n}\n```\n\n## Inspirations\n\nInspired by and builds on [openclaw-tracing](https://github.com/fengsxy/openclaw-tracing), a reference implementation for tracing OpenClaw executions.\n\n## License\n\nApache 2.0. See [LICENSE](LICENSE) for details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepsilla-cloud%2Fclawtrace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fepsilla-cloud%2Fclawtrace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepsilla-cloud%2Fclawtrace/lists"}