🕵️ @greenadda/aicodespy

Local-first AI token usage scanner — track how much you're burning across Claude Code, GitHub Copilot, and Antigravity, all in one beautiful dashboard.

---

✨ Features

• Multi-Provider Support — Scans logs from Claude Code, GitHub Copilot, and Antigravity (Windsurf/Codeium) simultaneously
• Live Dashboard — Interactive browser UI with token burn charts and prompt history, built with React & Recharts
• Prompt-Level Tracing — See exactly which prompts consumed the most tokens, sorted by Most Expensive or Most Recent
• Cross-Platform — Works on macOS, Linux, and Windows with automatic path detection
• Local & Private — All data stays on your machine. Zero telemetry, zero cloud uploads
• Incremental Scanning — Caches scan results for fast subsequent runs
• Antigravity Live API Polling — Dynamically connects to the local Antigravity Language Server to extract token telemetry in real-time

---

📦 Installation

npm install -g @greenadda/aicodespy

Or run directly with npx:

npx @greenadda/aicodespy

---

🚀 Usage

# Launch the dashboard (opens browser automatically)
aicodespy

# Specify a custom port
aicodespy -p 4000

# Fresh scan (clears cached data before starting)
aicodespy --clear-cache

# Skip auto-opening the browser
aicodespy --no-open

# Show all available options
aicodespy --help

CLI Options

Flag	Description
-p, --port <number>	Port to run the dashboard on (default: 3000)
--clear-cache	Clear cached scan data before starting
--no-open	Do not auto-open the browser
--claude-path <path>	Custom path to Claude projects storage
--copilot-path <path>	Custom path to Copilot logs folder
-V, --version	Output the version number
-h, --help	Display help for command

Note: If the default port is already in use, the tool automatically tries the next available port (up to 5 retries).

---

⚙️ Provider Configuration

Antigravity

No configuration needed. The tool automatically detects the running Antigravity Language Server process, extracts its port and CSRF token, and polls the local API for token usage data.

Requirement: Antigravity must be running in your IDE for this provider to work. The tool discovers the server via ps aux and connects over HTTP.

Tech Spec: Under the hood, Antigravity runs on the Codeium/Windsurf Language Server infrastructure (language_server_macos). The tool connects to its local gRPC-Connect API (exa.language_server_pb.LanguageServerService) on the dynamically assigned port (extension_server_port + 2) using the auto-discovered CSRF token for authentication.

Claude Code

The tool scans Claude Code's JSONL log files. It looks in these directories automatically:

Platform	Path
macOS	~/.claude/projects/
Linux	~/.config/claude/projects/
Windows	%APPDATA%\Claude\projects\

Requirement: Claude Code must have been used at least once. The tool recursively scans all subdirectories for .jsonl files.

GitHub Copilot

The tool scans Copilot's local log files (.log and .jsonl):

Platform	Path
macOS	~/.copilot/
Linux	~/.config/github-copilot/
Windows	%LOCALAPPDATA%\github-copilot\

Requirement: GitHub Copilot must have generated local logs. The tool recursively walks all subdirectories.

---

🖥️ Dashboard

The dashboard displays:

• Total Token Summary — Aggregated input/output tokens across all providers
• Token Burn by Provider — Bar chart comparing usage between Claude, Copilot, and Antigravity
• Top Prompts Table — Interactive list of prompts with token counts, sortable by:
  • 🔥 Most Expensive — Prompts that consumed the most tokens
  • 🕐 Most Recent — Your latest prompts across all providers

---

🏗️ Architecture

aicodespy/
├── bin/
│   └── cli.js              # CLI entry point (commander + express server)
├── src/
│   ├── scanner.js           # Core scanning engine with caching
│   ├── providers/
│   │   ├── BaseProvider.js  # Abstract base class for providers
│   │   ├── ClaudeProvider.js
│   │   ├── CopilotProvider.js
│   │   └── AntigravityProvider.js
│   └── dashboard/
│       └── index.html       # React + Recharts SPA dashboard
└── package.json

How It Works

1. Providers discover and parse log files (or poll APIs) for their respective AI tools
2. Scanner coordinates all providers, merges results, and maintains a disk cache at ~/.aicodespy/cache.json
3. Express API serves the aggregated stats at /api/stats
4. Dashboard fetches data from the API and renders interactive charts

---

🔧 API

The local server exposes a single REST endpoint:

GET /api/stats

Returns JSON with:

{
  "totalInputTokens": 5765200,
  "totalOutputTokens": 482300,
  "providers": {
    "Antigravity": { "inputTokens": 2120000, "outputTokens": 158000, "filesScanned": 1 },
    "Claude": { "inputTokens": 1845200, "outputTokens": 174800, "filesScanned": 3 },
    "Copilot": { "inputTokens": 1800000, "outputTokens": 149500, "filesScanned": 2 }
  },
  "topPrompts": [
    {
      "prompt": "Refactor the database layer to use the Repository pattern with TypeORM...",
      "inputTokens": 8500,
      "outputTokens": 19800,
      "timestamp": 1740400000000,
      "provider": "Claude"
    }
  ]
}

---

📋 Requirements

• Node.js ≥ 18
• At least one supported AI tool installed and having generated local logs:
  • Claude Code
  • GitHub Copilot
  • Antigravity (must be actively running in your IDE)

---

📄 License

MIT © GreenAdda

---

🗺️ Roadmap

• Node.js 24+ Support — When Node.js 24 becomes mainstream, the JSON cache will be replaced with native SQLite via @native-stack/stream-sql for faster queries, historical trend tracking, and date-range filtering