by tobilg
Unified local observability for AI coding assistants
# Add to your Claude Code skills
git clone https://github.com/tobilg/ai-observerUnified local observability for AI coding assistants
AI Observer is a self-hosted, single-binary, OpenTelemetry-compatible observability backend designed specifically for monitoring local AI coding tools like Claude Code, Gemini CLI, and OpenAI Codex CLI.
Track token usage, costs, API latency, error rates, and session activity across all your AI coding assistants in one unified dashboard—with real-time updates and zero external dependencies.
AI coding assistants are becoming essential development tools, but understanding their behavior and costs remains a challenge:
No comments yet. Be the first to share your thoughts!
linux/amd64 and linux/arm64



docker run -d \
-p 8080:8080 \
-p 4318:4318 \
-v ai-observer-data:/app/data \
--name ai-observer \
tobilg/ai-observer:latest
Dashboard: http://localhost:8080
Using a local directory for data persistence:
# Create a local data directory
mkdir -p ./ai-observer-data
# Run with local volume mount
docker run -d \
-p 8080:8080 \
-p 4318:4318 \
-v $(pwd)/ai-observer-data:/app/data \
-e AI_OBSERVER_DATABASE_PATH=/app/data/ai-observer.duckdb \
--name ai-observer \
tobilg/ai-observer:latest
This stores the DuckDB database in your local ./ai-observer-data directory, making it easy to backup or inspect.
brew tap tobilg/ai-observer
brew install ai-observer
ai-observer
Download the latest release for your platform from Releases, then:
./ai-observer
git clone https://github.com/tobilg/ai-observer.git
cd ai-observer
make setup # Install dependencies
make all # Build single binary with embedded frontend
./bin/ai-observer
| Variable | Default | Description |
|----------|---------|-------------|
| AI_OBSERVER_API_PORT | 8080 | HTTP server port (dashboard + API) |
| AI_OBSERVER_OTLP_PORT | 4318 | OTLP ingestion port |
| AI_OBSERVER_DATABASE_PATH | ./data/ai-observer.duckdb (binary) or /app/data/ai-observer.duckdb (Docker) | DuckDB database file path |
| AI_OBSERVER_FRONTEND_URL | http://localhost:5173 | Allowed CORS origin (dev mode) |
| AI_OBSERVER_LOG_LEVEL | INFO | Log level: DEBUG, INFO, WARN, ERROR |
CORS and WebSocket origins allow AI_OBSERVER_FRONTEND_URL plus http://localhost:5173 and http://localhost:8080; set AI_OBSERVER_FRONTEND_URL when serving a custom UI origin.
ai-observer [command] [options]
Commands:
| Command | Description |
|---------|-------------|
| import | Import local sessions from AI tool files |
| export | Export telemetry data to Parquet files |
| delete | Delete telemetry data from database |
| setup | Show setup instructions for AI tools |
| serve | Start the OTLP server (default if no command) |
Global Options:
| Option | Description |
|--------|-------------|
| -h, --help | Show help message and exit |
| -v, --version | Show version information and exit |
Examples:
# Start the server (default, no command needed)
ai-observer
# Show version
ai-observer --version
# Show setup instructions for Claude Code
ai-observer setup claude-code
# Import data from all AI tools
ai-observer import all
# Export data to Parquet files
ai-observer export all --output ./export
# Delete data in a date range
ai-observer delete all --from 2025-01-01 --to 2025-01-31
Import historical session data from local AI coding tool files into AI Observer.
ai-observer import [claude-code|codex|gemini|all] [options]
| Option | Description |
|--------|-------------|
| --from DATE | Only import sessions from DATE (YYYY-MM-DD) |
| --to DATE | Only import sessions up to DATE (YYYY-MM-DD) |
| --force | Re-import already imported files |
| --dry-run | Show what would be imported without making changes |
| --skip-confirm | Skip confirmation prompt |
| --purge | Delete existing data in time range before importing |
| --pricing-mode MODE | Cost calculation mode for Claude: auto (default), calculate, display |
| --verbose | Show detailed progress |
File locations:
| Tool | Default Location |
|------|------------------|
| Claude Code | ~/.claude/projects/**/*.jsonl |
| Codex CLI | ~/.codex/sessions/*.jsonl |
| Gemini CLI | ~/.gemini/tmp/**/session-*.json |
Override with environment variables: AI_OBSERVER_CLAUDE_PATH, AI_OBSERVER_CODEX_PATH, AI_OBSERVER_GEMINI_PATH
Examples:
# Import from all tools
ai-observer import all
# Import Claude data from specific date range
ai-observer import claude-code --from 2025-01-01 --to 2025-12-31
# Dry run to see what would be imported
ai-observer import all --dry-run
# Force re-import and recalculate costs
ai-observer import claude-code --force --pricing-mode calculate
See docs/import.md for detailed documentation and docs/pricing.md for pricing calculation details.
Export telemetry data to portable Parquet files with an optional DuckDB views database.
ai-observer export [claude-code|codex|gemini|all] --output <directory> [options]
| Option | Description |
|--------|-------------|
| --output DIR | Output directory (required) |
| --from DATE | Start date filter (YYYY-MM-DD) |
| --to DATE | End date filter (YYYY-MM-DD) |
| --from-files | Read from raw JSON/JSONL files instead of database |
| --zip | Create single ZIP archive of exported files |
| --dry-run | Preview what would be exported |
| --verbose | Show detailed progress |
| --yes | Skip confirmation prompt |
Output files:
traces.parquet — All trace/span datalogs.parquet — All log recordsmetrics.parquet — All metric data pointsai-observer-export-{SOURCE}-{RANGE}.duckdb — Views database with relative pathsExamples:
# Export all data from database
ai-observer export all --output ./export
# Export Claude data with date filter
ai-observer export claude-code --output ./export --from 2025-01-01 --to 2025-01-15
# Export to ZIP archive
ai-observer export all --output ./export --zip
# Export directly from raw files (without prior import)
ai-observer export claude-code --output ./export --from-files
# Dry run to preview export
ai-observer export all --output ./export --dry-run
See docs/export.md for detailed documentation.
Delete telemetry data from the database by time range.
ai-observer delete [logs|metrics|traces|all] --from DATE --to DATE [options]
| Option | Description |
|--------|-------------|
| --from DATE | Start date (YYYY-MM-DD, required) |
| --to DATE | End date (YYYY-MM-DD, required) |
| --service NAME | Only delete data for specific service |
| --yes | Skip confirmation prompt |
Examples:
# Delete all data in a date range
ai-observer delete all --from 2025-01-01 --to 2025-01-31
# Delete only logs in a date range
ai-observer delete logs --from 2025-01-01 --to 2025-01-31
# Delete only Claude Code data
ai-observer delete all --from 2025-01-01 --to 2025-01-31 --service claude-code
# Skip confirmation prompt
ai-observer delete all --from 2025-01-01 --to 2025-01-31 --yes
Configure the following environment variables:
# Enable telemetry (required)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
# Configure exporters
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
# Set OTLP endpoint (HTTP)
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
# Set shorter intervals
export OTEL_METRIC_EXPORT_INTERVAL=10000 # 10 seconds (default: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000 # 5 seconds (default: 5000ms)
Add these to your ~/.bashrc, ~/.zshrc, or shell profile to persist across sessions.
Claude Code will then automatically send metrics and events to AI Observer.