{"id":47766404,"url":"https://github.com/briqt/agent-usage","last_synced_at":"2026-04-14T08:02:11.127Z","repository":{"id":348849760,"uuid":"1200112725","full_name":"briqt/agent-usage","owner":"briqt","description":"Lightweight cross-platform AI coding agent usage \u0026 cost tracker. Single binary, SQLite, web dashboard. | 轻量跨平台 AI 编程工具用量与费用追踪器，单二进制、SQLite 存储、Web 仪表板。","archived":false,"fork":false,"pushed_at":"2026-04-08T09:19:22.000Z","size":846,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T11:04:13.579Z","etag":null,"topics":["ai","claude-code","codex","coding-agent","cost-tracking","dashboard","golang","observability","sqlite","usage-tracking"],"latest_commit_sha":null,"homepage":null,"language":"Go","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/briqt.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"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":null,"dco":null,"cla":null}},"created_at":"2026-04-03T03:44:11.000Z","updated_at":"2026-04-08T09:41:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/briqt/agent-usage","commit_stats":null,"previous_names":["briqt/agent-usage"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/briqt/agent-usage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/briqt%2Fagent-usage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/briqt%2Fagent-usage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/briqt%2Fagent-usage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/briqt%2Fagent-usage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/briqt","download_url":"https://codeload.github.com/briqt/agent-usage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/briqt%2Fagent-usage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31787263,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T02:24:21.117Z","status":"ssl_error","status_checked_at":"2026-04-14T02:24:20.627Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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","cost-tracking","dashboard","golang","observability","sqlite","usage-tracking"],"created_at":"2026-04-03T07:04:56.029Z","updated_at":"2026-04-14T08:02:11.084Z","avatar_url":"https://github.com/briqt.png","language":"Go","readme":"# agent-usage\n\n[![Go](https://img.shields.io/badge/Go-1.25+-00ADD8?logo=go\u0026logoColor=white)](https://go.dev)\n[![License: MIT](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-blue)]()\n[![Docker](https://img.shields.io/badge/Docker-ghcr.io-blue?logo=docker)](https://ghcr.io/briqt/agent-usage)\n\nLightweight, cross-platform AI coding agent usage \u0026 cost tracker.  \nSingle binary + SQLite — zero infrastructure required.\n\n**[中文文档](README_CN.md)**\n\nCollects local session data from Claude Code, Codex, OpenClaw, OpenCode and other AI coding agents, calculates costs automatically, and presents token usage, cost trends, and session details through a web dashboard.\n\n![Dashboard](docs/dashboard.png)\n\n## Features\n\n- 📁 **Local file parsing** — reads Claude Code, Codex CLI, OpenClaw session files and OpenCode SQLite database directly\n- 💰 **Automatic cost calculation** — fetches model pricing from [litellm](https://github.com/BerriAI/litellm), supports backfill when prices update\n- 🗄️ **SQLite storage** — single file, zero ops, data is correctable\n- 📊 **Web dashboard** — dark-themed UI with ECharts: cost breakdown, token trends, session list\n- 🔄 **Incremental scanning** — watches for new sessions, deduplicates automatically\n- 📦 **Single binary** — `go:embed` packs the web UI into the executable\n- 🖥️ **Cross-platform** — Linux, macOS, Windows\n\n## Quick Start (Docker)\n\n```bash\n# One command to start\nmkdir -p ./data \u0026\u0026 docker compose up -d\n\n# Open dashboard\nopen http://localhost:9800\n```\n\nThe default `docker-compose.yml` mounts `~/.claude/projects`, `~/.codex/sessions`, `~/.openclaw/agents`, and `~/.local/share/opencode` read-only. Data persists in `./data/`.\n\nThe container uses `config.docker.yaml` by default (binds to `0.0.0.0`, stores data in `/data/`). To override, mount your own config:\n\n```yaml\n# In docker-compose.yml, uncomment:\nvolumes:\n  - ./config.yaml:/etc/agent-usage/config.yaml:ro\n```\n\nSee [Docker Details](#docker-details) for UID/GID permissions and local builds.\n\n## Query Usage from Agent Conversations\n\nThe skill works standalone — no need to install or run the agent-usage server. It parses local JSONL session files directly. If the agent-usage server is detected, it automatically switches to API queries for more accurate cost data.\n\n```bash\n# Installed via vercel-labs/skills, supports Claude Code, Cursor, Kiro, and 40+ agents\nnpx skills add briqt/agent-usage -y\n```\n\nOnce installed, try: `查下 agent usage`、`agent usage 统计` or `check agent usage`. See [`skills/agent-usage/SKILL.md`](skills/agent-usage/SKILL.md) for details.\n\n## Configuration\n\n```yaml\nserver:\n  port: 9800\n  bind_address: \"127.0.0.1\"  # use \"0.0.0.0\" for remote access\n\ncollectors:\n  claude:\n    enabled: true\n    paths:\n      - \"~/.claude/projects\"\n    scan_interval: 60s\n  codex:\n    enabled: true\n    paths:\n      - \"~/.codex/sessions\"\n    scan_interval: 60s\n  openclaw:\n    enabled: true\n    paths:\n      - \"~/.openclaw/agents\"\n    scan_interval: 60s\n  opencode:\n    enabled: true\n    paths:\n      - \"~/.local/share/opencode/opencode.db\"\n    scan_interval: 60s\n\nstorage:\n  path: \"./agent-usage.db\"\n\npricing:\n  sync_interval: 1h  # fetched from GitHub; set HTTPS_PROXY env var if this fails\n```\n\nConfig search order: `--config` flag \u003e `/etc/agent-usage/config.yaml` \u003e `./config.yaml`.\n\n## Build from Source\n\n```bash\n# Clone\ngit clone https://github.com/briqt/agent-usage.git\ncd agent-usage\n\n# Build\ngo build -o agent-usage .\n\n# Edit config\ncp config.yaml config.local.yaml\n# Adjust paths if needed\n\n# Run\n./agent-usage\n\n# Open dashboard\nopen http://localhost:9800\n```\n\n## Supported Data Sources\n\n| Source | Session Location | Format |\n|--------|-----------------|--------|\n| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `~/.claude/projects/\u003cproject\u003e/\u003csession\u003e.jsonl` | JSONL |\n| [Codex CLI](https://github.com/openai/codex) | `~/.codex/sessions/\u003cyear\u003e/\u003cmonth\u003e/\u003cday\u003e/\u003csession\u003e.jsonl` | JSONL |\n| [OpenClaw](https://github.com/openclaw/openclaw) | `~/.openclaw/agents/\u003cagentId\u003e/sessions/\u003csessionId\u003e.jsonl` | JSONL |\n| [OpenCode](https://github.com/anomalyco/opencode) | `~/.local/share/opencode/opencode.db` | SQLite |\n\n### Adding New Sources\n\nEach source needs a collector that:\n1. Scans session directories for JSONL files\n2. Parses entries and extracts token usage per API call\n3. Writes records to SQLite via the storage layer\n\nSee `internal/collector/claude.go` as a reference implementation.\n\n## Dashboard\n\nThe web dashboard provides:\n\n- **Sticky top bar** — time presets, granularity, source filter (Claude/Codex/OpenClaw/OpenCode), auto-refresh\n- **Summary cards** — total tokens, cost, sessions, prompts, API calls\n- **Token usage** — stacked bar chart (input/output/cache read/cache write)\n- **Cost trend** — stacked bar chart by model with consistent color mapping\n- **Cost by model** — doughnut chart with percentage labels\n- **Session list** — sortable, filterable table with expandable per-model detail\n- **Dark/Light theme** — system-aware with manual toggle\n- **i18n** — English and Chinese\n- **Timezone handling** — all timestamps are stored in UTC; the frontend automatically converts to your browser's local timezone for date pickers, chart X-axis labels, and session timestamps\n\n## Architecture\n\n```\nagent-usage\n├── main.go                     # Entry point, orchestrates components\n├── config.yaml                 # Configuration\n├── internal/\n│   ├── config/                 # YAML config loader\n│   ├── collector/\n│   │   ├── collector.go        # Collector interface\n│   │   ├── claude.go           # Claude Code session scanner\n│   │   ├── claude_process.go   # Claude Code JSONL parser\n│   │   ├── codex.go            # Codex CLI JSONL parser\n│   │   ├── openclaw.go         # OpenClaw session scanner\n│   │   ├── openclaw_process.go # OpenClaw JSONL parser\n│   │   └── opencode.go         # OpenCode SQLite collector\n│   ├── pricing/                # litellm price fetcher + cost formula\n│   ├── storage/\n│   │   ├── sqlite.go           # DB init + migrations\n│   │   ├── api.go              # Query types + read operations\n│   │   ├── queries.go          # Write operations\n│   │   └── costs.go            # Cost recalculation + backfill\n│   └── server/\n│       ├── server.go           # HTTP server + REST API\n│       └── static/             # Embedded web UI (HTML + JS + ECharts)\n└── agent-usage.db              # SQLite database (generated at runtime)\n```\n\n## Cost Calculation\n\nPricing is fetched from [litellm's model price database](https://github.com/BerriAI/litellm/blob/main/model_prices_and_context_window.json) and stored locally.\n\n```\ncost = (input - cache_read - cache_creation) × input_price\n     + cache_creation × cache_creation_price\n     + cache_read × cache_read_price\n     + output × output_price\n```\n\nWhen prices update, historical records are automatically backfilled.\n\n## API Endpoints\n\nAll endpoints accept `from` and `to` (YYYY-MM-DD) query parameters. Optional: `source` (`claude`, `codex`, `openclaw`, `opencode`) to filter by agent, `granularity` (`1m`, `30m`, `1h`, `6h`, `12h`, `1d`, `1w`, `1M`) for time-series endpoints.\n\n| Endpoint | Description |\n|----------|-------------|\n| `GET /api/stats` | Summary: total cost, tokens, sessions, prompts, API calls |\n| `GET /api/cost-by-model` | Cost grouped by model |\n| `GET /api/cost-over-time` | Cost time series (supports `granularity`) |\n| `GET /api/tokens-over-time` | Token usage time series (supports `granularity`) |\n| `GET /api/sessions` | Session list with cost/token totals |\n| `GET /api/session-detail?session_id=ID` | Per-model breakdown for a session |\n\nInvalid date formats or reversed date ranges return a `400` JSON error with a descriptive message.\n\n## Tech Stack\n\n- **Go** — pure Go, no CGO required\n- **SQLite** via [`modernc.org/sqlite`](https://pkg.go.dev/modernc.org/sqlite) — pure Go SQLite driver\n- **ECharts** — charting library\n- **`go:embed`** — single binary deployment\n\n## Docker Details\n\nPre-built multi-arch images (amd64 + arm64) are published to `ghcr.io/briqt/agent-usage`.\n\nThe default `docker-compose.yml` runs as UID 1000. If your host user has a different UID, edit the `user:` field:\n\n```bash\n# Check your UID/GID\nid -u  # e.g. 1000\nid -g  # e.g. 1000\n\n# Edit docker-compose.yml: user: \"YOUR_UID:YOUR_GID\"\n```\n\nThis is required because `~/.claude/projects` is mode 700 — only the owning UID can read it.\n\n### Building locally\n\n```bash\ndocker build -t agent-usage:local .\n\n# For China mainland, use GOPROXY:\ndocker build --build-arg GOPROXY=https://goproxy.cn,direct -t agent-usage:local .\n```\n\n## Roadmap\n\n- [ ] More agent sources (Cursor, Copilot, OpenCode, etc.)\n- [ ] OTLP HTTP receiver for real-time telemetry\n- [ ] OS service management (systemd / launchd / Windows Service)\n- [ ] Export to CSV/JSON\n- [ ] Alerting (cost thresholds)\n- [ ] Multi-user support\n\n## Community\n\nJoin the discussion at [Linux.do](https://linux.do/t/topic/1922004).\n\n## License\n\n[Apache 2.0](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbriqt%2Fagent-usage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbriqt%2Fagent-usage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbriqt%2Fagent-usage/lists"}