{"id":48840947,"url":"https://github.com/ramo-dev/tokwatch","last_synced_at":"2026-04-15T02:11:45.799Z","repository":{"id":344572050,"uuid":"1182251111","full_name":"ramo-dev/tokwatch","owner":"ramo-dev","description":"TokWatch monitors token usage across Claude Code, OpenCode, Ollama, Cursor, Antigravity, and Windsurf etc Starts in under 300ms.","archived":false,"fork":false,"pushed_at":"2026-03-15T13:32:57.000Z","size":101,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-15T22:51:44.749Z","etag":null,"topics":["claude","cli","gpt","gui","tokens"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/ramo-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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-03-15T08:56:20.000Z","updated_at":"2026-03-15T10:59:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ramo-dev/tokwatch","commit_stats":null,"previous_names":["ramo-dev/tokwatch"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ramo-dev/tokwatch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramo-dev%2Ftokwatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramo-dev%2Ftokwatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramo-dev%2Ftokwatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramo-dev%2Ftokwatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ramo-dev","download_url":"https://codeload.github.com/ramo-dev/tokwatch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramo-dev%2Ftokwatch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31822914,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"online","status_checked_at":"2026-04-15T02:00:06.175Z","response_time":63,"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":["claude","cli","gpt","gui","tokens"],"created_at":"2026-04-15T02:11:45.303Z","updated_at":"2026-04-15T02:11:45.790Z","avatar_url":"https://github.com/ramo-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TokWatch\n\nYour local token accountant - because \"how much did I just spend?\" shouldn't require a spreadsheet. TokWatch monitors token usage across Claude Code, OpenCode, Ollama, Cursor, Antigravity, and Windsurf, persists it to SQLite, and surfaces it however you like: terminal, HTTP, a proper web dashboard, or an interactive blessed CLI. Starts in under 300ms.\n\n## Features\n\n- **Multi-tool support** — Claude Code, OpenCode, Ollama, Cursor, Antigravity, Windsurf\n- **Multiple output modes** — Terminal, HTTP server, Web UI, CLI\n- **Persistent storage** — SQLite keeps your cumulative totals across sessions\n- **Configurable** — pick exactly which tools you care about\n- **Web dashboard** — a real visual UI, built with Vite\n- **Monorepo** — Bun workspaces, cleanly split into API, CLI, and Web\n\n## Quick Start\n\n```bash\n# Install dependencies\nbun install\n\n# One-shot terminal output\nbun run index.ts\n\n# Or launch a specific app directly\nbun run --filter cli dev    # Interactive CLI (blessed)\nbun run --filter web dev    # Web dashboard\n```\n\n## Monorepo Commands\n\n```bash\n# Bring everything up at once\nbun run dev\n\n# Or target just what you need\nbun run dev:web     # Web UI only\nbun run dev:cli     # CLI only\n\n# Run from root with flags\nbun run index.ts --http\nbun run index.ts --web\n```\n\n## CLI Options\n\n| Flag | Description |\n|------|-------------|\n| `--all`, `-a` | Show all plugins, not just defaults |\n| `--http` | Start the HTTP API server |\n| `--web` | Start the web UI |\n| `--list`, `-l` | List every available plugin |\n| `--set-default=\u003cplugins\u003e` | Persist a default plugin set (comma-separated) |\n| `--plugins=\u003cplugins\u003e` | Enable specific plugins for this run |\n| `--theme=\u003cdark\\|light\u003e` | Set your theme preference |\n| `--interval=\u003cms\u003e` | Poll interval in milliseconds (default: 60000) |\n| `--port=\u003cport\u003e` | HTTP server port (default: 7850) |\n\n## Examples\n\n```bash\n# See what plugins are available\nbun run index.ts --list\n\n# Save a default set so you don't repeat yourself\nbun run index.ts --set-default=claude-code,opencode,ollama\n\n# Show everything at once\nbun run index.ts --all\n\n# HTTP server with a tighter poll interval on a custom port\nbun run index.ts --http --interval=30000 --port=9000\n\n# Interactive CLI\nbun run --filter cli dev --port=7850\n\n# Web dashboard\nbun run --filter web dev\n```\n\n## HTTP API\n\nStart with `--http` and hit the metrics endpoint:\n\n```\nGET http://localhost:7850/metrics\n```\n\nResponse:\n\n```json\n{\n  \"plugins\": [\n    {\n      \"plugin\": \"claude-code\",\n      \"used\": 19700000,\n      \"limit\": null,\n      \"remaining\": null,\n      \"resetAt\": \"...\"\n    }\n  ],\n  \"cumulative\": [\n    {\n      \"plugin\": \"claude-code\",\n      \"total_used\": 59000000,\n      \"last_seen\": \"2026-03-15 08:27:05\"\n    }\n  ],\n  \"timestamp\": \"2026-03-15T08:30:00.000Z\"\n}\n```\n\n## Web UI\n\n```bash\nbun run index.ts --web\n# or\nbun run --filter web dev\n```\n\n## CLI UI (Blessed)\n\n```bash\nbun run --filter cli dev --port=7850\n```\n\nKeybindings once you're in:\n\n| Key | Action |\n|-----|--------|\n| `t` | Toggle between current and cumulative view |\n| `r` | Force a refresh |\n| `q` | Quit |\n\n## Configuration\n\nConfig lives at `~/.config/tokwatch/config.json` and is written automatically on first run:\n\n```json\n{\n  \"plugins\": [\"claude-code\", \"opencode\", \"ollama\", \"cursor\", \"antigravity\", \"windsurf\"],\n  \"defaultPlugins\": [\"claude-code\", \"opencode\", \"ollama\"],\n  \"theme\": \"dark\",\n  \"output\": \"terminal\",\n  \"interval\": 60000,\n  \"port\": 7850,\n  \"showAll\": false\n}\n```\n\n## Adding Custom Plugins\n\nDrop a new file in `apps/api/plugins/`:\n\n```typescript\n// apps/api/plugins/my-tool.ts\nimport type { TokenPlugin, PluginResult } from \"../core/types\"\n\nexport const myToolPlugin: TokenPlugin = {\n  name: \"my-tool\",\n  async poll(): Promise {\n    return {\n      plugin: \"my-tool\",\n      used: 1000000,\n      limit: null,\n      remaining: null,\n      resetAt: null,\n    }\n  },\n}\n```\n\nThen register it in `apps/api/plugins/index.ts` and it'll show up like any other plugin.\n\n## Project Structure\n\n```\ntokwatch/\n├── package.json              # Monorepo root\n├── index.ts                  # Main entry point\n├── apps/\n│   ├── api/                  # Core API library\n│   │   ├── core/             # Runner, store, types, config\n│   │   ├── outputs/          # Terminal, HTTP output\n│   │   └── plugins/          # Tool plugins\n│   ├── cli/                  # Blessed CLI app\n│   └── web/                  # Vite + React web dashboard\n```\n\n## Tech Stack\n\n- **Runtime** — Bun\n- **Database** — bun:sqlite\n- **Web** — Vite + React + Tailwind CSS\n- **CLI** — Blessed + TypeScript\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framo-dev%2Ftokwatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Framo-dev%2Ftokwatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framo-dev%2Ftokwatch/lists"}