LLM Observer Documentation

LLM Observer is an AI usage analytics tool that tracks costs, tokens, and usage patterns across multiple AI coding providers. It runs locally on your machine, reads your existing session data, and serves a real-time analytics dashboard. Your data never leaves your machine.

Installation

npm (recommended, all platforms)

npm install -g llm-observer
llm-observer start

Requires Node.js 18 or later.

Desktop app

Prefer a native app with no Node.js required? Download the signed installer for your OS from the releases page — .dmg/.app.tar.gz for macOS, .deb/.rpm/.AppImage for Linux, .exe/.msi for Windows.

First Run

After installing, run:

llm-observer start

LLM Observer automatically detects your local AI tool history (Claude Code, Cursor, Aider, GitHub Copilot, Windsurf, Cline, and OpenAI Codex CLI) and launches the dashboard at http://localhost:4001 — no API keys, no account, no cloud sign-up required for this part.

Configuration

LLM Observer's local database and settings live at ~/.llm-observer/data.db (override the directory with the LLM_OBSERVER_DATA_DIR environment variable). Most settings — session sources, budgets, PII redaction, drift detection — are configured from the dashboard's Settings page, not a hand-edited config file.

Environment variableDefaultDescription
LLM_OBSERVER_PORT4001Dashboard and API port
LLM_OBSERVER_HOST127.0.0.1Bind address
LLM_OBSERVER_DATA_DIR~/.llm-observerDatabase and config location
LLM_OBSERVER_PROXY_PORT4000Proxy port (when enabled)

Provider Overview

Session tracking works by reading local files that AI coding tools already write — no API keys or configuration needed for this path:

  • Claude Code: reads JSONL session history.
  • Cursor IDE: reads its local SQLite tracking database.
  • Aider: reads structured analytics logs.
  • GitHub Copilot, Windsurf, Cline / Roo Code: read each extension's local storage.
  • OpenAI Codex CLI: reads its JSONL session logs.

For billing-accurate numbers instead of estimates, you can optionally add an Anthropic or OpenAI Admin API key on the Sync page — this polls the provider's own usage API.

Sessions Tab

Browse every AI conversation with full metadata. Sort by cost to find expensive sessions instantly. Sortable columns include Date, Provider, Model, Duration, and Estimated Cost.

KPI Cards

Visualize your LLM usage through high-level metrics including total tokens, estimated cost, and average latency per provider.

Costs Tab

Detailed breakdown of expenditures across specific timeframes. Filter by project or model to optimize your AI spend.