Documentation

• Import Command — Import historical session data from local AI tool files
• Export Command — Export telemetry data to Parquet files for archiving and sharing
• Pricing System — Cost calculation for Claude, Codex, and Gemini models

Screenshots

Dashboard

Metrics View

Logs View

Traces View

Quick Start

Using Docker (Recommended)

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.

Using Homebrew (macOS Apple Silicon)

brew tap tobilg/ai-observer
brew install ai-observer
ai-observer

Using Binary

Download the latest release for your platform from Releases, then:

./ai-observer

Building from Source

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

Configuration

Environment Variables

| 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.

CLI Options

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 Command

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 Command

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 data
• logs.parquet — All log records
• metrics.parquet — All metric data points
• ai-observer-export-{SOURCE}-{RANGE}.duckdb — Views database with relative paths

Examples:

# 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 Command

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

AI Tool Setup

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.