📊 OpenCode Monitor

OpenCode Monitor is a CLI tool for monitoring and analyzing OpenCode AI coding sessions.

Transform your OpenCode usage data into beautiful, actionable insights with comprehensive analytics, real-time monitoring, and professional reporting capabilities.

⚠️ Disclaimer - This application is not affiliated with OpenCode AI. It is an independent community tool for monitoring OpenCode usage.

🌟 Features

💼 Professional Analytics

• 📈 Comprehensive Reports - Daily, weekly, and monthly usage breakdowns
• 💰 Cost Tracking - Accurate cost calculations for multiple AI models
• 🌍 Multi-Currency Support - Display costs in USD, GBP, EUR, JPY, CNY, INR, or any currency with live exchange rates
• 📊 Model Analytics - Detailed breakdown of usage per AI model with --breakdown flag
• 🔍 Single Model Deep Dive - ocmonitor model <name> drills into one model with dates, costs, speed, and tool stats
• 📋 Project Analytics - Track costs and token usage by coding project
• ⏱️ Performance Metrics - Session duration and processing time tracking
• 📅 Flexible Week Boundaries - Customize weekly reports with 7 start day options (Monday-Sunday)
• 🚀 Output Speed Tracking - Average output tokens per second for each model in reports
• 🔗 Workflow Grouping - Automatically groups main sessions with their sub-agent sessions (explore, etc.)

🗄️ Storage Support

• SQLite Database - Native support for OpenCode v1.2.0+ SQLite format (~/.local/share/opencode/opencode.db)
• Legacy File Support - Backwards compatible with pre-v1.2.0 JSON file storage
• Auto Detection - Automatically detects and uses the appropriate storage backend
• Hierarchical Sessions - Parent/sub-agent relationships from SQLite displayed as tree view

🎨 Beautiful User Interface

• 🌈 Rich Terminal UI - Professional design with clean styling and optimal space utilization
• 📊 Progress Bars - Visual indicators for cost quotas, context usage, and session time
• 🚥 Color Coding - Green/yellow/red status indicators based on usage thresholds
• 📱 Live Dashboard - Real-time monitoring with project names and session titles
• ⏰ Session Time Tracking - 5-hour session progress bar with color-coded time alerts
• 🔧 Tool Usage Panel - Track tool success rates (bash, read, edit, etc.) in live dashboard

📤 Data Export & Integration

• 📋 CSV Export - Spreadsheet-compatible exports with metadata
• 🔄 JSON Export - Machine-readable exports for custom integrations
• 📊 Multiple Report Types - Sessions, daily, weekly, monthly, model, and project reports
• 📈 Prometheus Metrics - Real-time metrics endpoint for Grafana/Prometheus integration

🚀 Quick Start

Installation

Option 1: pip / PyPI (Recommended)

pip install opencode-monitor

With optional extras:

pip install "opencode-monitor[charts,export]"

Option 2: uvx (Run without installing)

uvx opencode-monitor live

Option 3: uv tool install

uv installs the tool in an isolated environment.

uv tool install opencode-monitor

# With optional extras
uv tool install "opencode-monitor[charts,export]"

# Easy to upgrade
uv tool upgrade opencode-monitor

Option 4: pipx Installation (Cross Platform)

pipx creates isolated environments and works on all platforms (including Arch Linux, Ubuntu, macOS, etc.).

pipx install opencode-monitor

With optional extras:

pipx install "opencode-monitor[charts,export]"

Option 5: Install from source

git clone https://github.com/Shlomob/ocmonitor-share.git
cd ocmonitor-share
python3 -m pip install -e .

Option 6: Dockerized Installation

docker compose build

Usage example:

docker compose run --rm ocmonitor sessions

If your host OpenCode data is not in ~/.local/share/opencode, set OPENCODE_DATA_DIR before running:

OPENCODE_DATA_DIR=/your/path/to/opencode/data/dir docker compose run --rm ocmonitor sessions

Basic Usage

# Real-time monitoring dashboard
ocmonitor live

# View sessions history
ocmonitor sessions

# Daily usage breakdown (add --breakdown for per-model detail)
ocmonitor daily
ocmonitor daily --breakdown

# Deep dive into a specific model
ocmonitor model claude-sonnet-4-5

Command Reference

Command	Description
ocmonitor live	Real-time monitoring dashboard
ocmonitor sessions	All sessions summary with workflow grouping
ocmonitor session <path>	Single session detail
ocmonitor daily	Daily usage breakdown
ocmonitor weekly	Weekly usage breakdown
ocmonitor monthly	Monthly usage breakdown
ocmonitor models	Model usage statistics
ocmonitor model <name>	Single model deep dive
ocmonitor projects	Project usage statistics
ocmonitor agents	List detected agents and types
ocmonitor export <type>	Export to CSV/JSON
ocmonitor metrics	Prometheus metrics endpoint
ocmonitor config show	Show current configuration

Global Options

These options can be used with any command:

ocmonitor --theme light sessions     # Override theme (dark/light)
ocmonitor --verbose daily            # Show detailed error traces
ocmonitor --config /path/config.toml sessions  # Use custom config file
ocmonitor --no-remote sessions       # Disable remote pricing fallback

📖 Documentation

• Quick Start Guide - Get up and running in 5 minutes
• Manual Test Guide - Comprehensive testing instructions
• Contributing Guidelines - How to contribute to the project

🎯 Use Cases

Individual Developers

• Cost Management - Track your AI usage costs across different models and projects
• Usage Optimization - Identify patterns in your coding sessions with session time tracking
• Performance Monitoring - Monitor session efficiency and token usage with real-time dashboards
• Project Analytics - Understand which projects consume the most AI resources

Development Teams

• Team Analytics - Aggregate usage statistics across team members and projects
• Budget Planning - Forecast AI costs based on usage trends and project breakdowns
• Model Comparison - Compare performance and costs across different AI models
• Session Management - Track coding session durations and productivity patterns

Organizations

• Resource Planning - Plan AI resource allocation and budgets by project
• Usage Reporting - Generate professional reports for stakeholders with export capabilities
• Cost Attribution - Track AI costs by project, team, and time period
• Quality Monitoring - Monitor session lengths and usage patterns for optimization

📊 Example Output

📸 Screenshots: The following examples include both text output and clickable screenshots. To add your own screenshots, place PNG files in the screenshots/ directory with the corresponding filenames.

Sessions Summary

Click image to view full-size screenshot of sessions summary output

Workflow Grouping

By default, sessions are grouped into workflows - a main session combined with its sub-agent sessions (like explore). This gives you a complete picture of your coding session including all agent activity.

# Sessions with workflow grouping (default)
ocmonitor sessions

# Sessions without grouping (flat list)
ocmonitor sessions --no-group

# Force a specific data source
ocmonitor sessions --source sqlite   # Force SQLite (v1.2.0+)
ocmonitor sessions --source files    # Force legacy file storage

# List detected agents and their types
ocmonitor agents

Workflow Features: - Main sessions and sub-agent sessions are visually grouped with tree-style formatting - Aggregated tokens and costs are shown for the entire workflow - Sub-agent count displayed in the Agent column (e.g., +2 means 2 sub-agents) - Use --no-group to see individual sessions without grouping

Time-Based Reporting

ocmonitor daily|weekly|monthly <path> [--breakdown]

Time-based usage breakdown with optional per-model cost analysis.

# Daily breakdown
ocmonitor daily

# Weekly breakdown with per-model breakdown
ocmonitor weekly --breakdown

# Monthly breakdown
ocmonitor monthly

# Weekly with custom start day
ocmonitor weekly --start-day friday --breakdown

--breakdown Flag: Shows token consumption and cost per model within each time period (daily/weekly/monthly), making it easy to see which models are consuming resources.

Supported days: monday, tuesday, wednesday, thursday, friday, saturday, sunday

Live Monitoring Commands

ocmonitor live <path>

Real-time monitoring dashboard that updates automatically.

# Start live monitoring (updates every 3 seconds by default)
ocmonitor live

# Custom update interval (in seconds)
ocmonitor live --interval 10

# Pick a workflow by readable title before launching
# (also enables interactive switching controls by default)
ocmonitor live --pick

# Pin live monitor to a specific workflow/session ID
ocmonitor live --session-id ses_abc123

# Force a specific data source
ocmonitor live --source sqlite    # Force SQLite (v1.2.0+)
ocmonitor live --source files     # Force legacy file storage

# Enable interactive switching while live monitor runs (experimental)
ocmonitor live --interactive-switch

If --session-id is pinned and the selected workflow is no longer active, live monitoring stops with a clear message. When both --session-id and --pick are supplied to ocmonitor live, --session-id takes precedence and --pick is ignored.

Features: - 🔄 Auto-refreshing display with professional UI design - 📊 Real-time cost tracking with progress indicators - ⏱️ Live session duration with 5-hour progress bar - 📈 Token usage updates and context window monitoring - 🚀 Output Rate - Rolling 5-minute window showing output tokens per second - 🚦 Color-coded status indicators and time alerts - 📂 Project name display for better context - 📝 Human-readable session titles instead of cryptic IDs - 🔗 Workflow Tracking - Automatically tracks entire workflow including sub-agents (explore, etc.) - 🔧 Tool Usage Stats - Shows success rates for tools (bash, read, edit, etc.) with color-coded progress bars

Click image to view full-size screenshot of the live monitoring dashboard

Model Usage Breakdown

Click image to view full-size screenshot of model usage analytics

# Filter by timeframe or date range
ocmonitor models --timeframe weekly
ocmonitor models --start-date 2026-01-01 --end-date 2026-02-01
ocmonitor projects --timeframe monthly
ocmonitor projects --start-date 2026-01-01 --end-date 2026-02-01

Model Analytics Features: - Per-model token usage and cost breakdown - Cost percentage distribution across models - Speed Column - Average output tokens per second for each model - Session and interaction counts per model

Single Model Detail

# Drill into one model by exact or partial name
ocmonitor model claude-sonnet-4-5
ocmonitor model sonnet        # lists all sonnet variants to pick from
ocmonitor model opus -f json  # JSON output

Output:

╭─ Model Detail: claude-sonnet-4-5 ─────────────────────────────╮
│ First Used      2025-09-15                                      │
│ Last Used       2026-02-28                                      │
│ Sessions        42                                              │
│ Days Used       28                                              │
│ Interactions    1,247                                           │
│                                                                 │
│ Input Tokens    2,451,320                                       │
│ Output Tokens   489,210                                         │
│ Cache Read      1,102,400                                       │
│ Cache Write     312,500                                         │
│                                                                 │
│ Total Cost      $47.23                                          │
│ Avg/Day         $1.69                                           │
│ Avg/Session     $1.12                                           │
│                                                                 │
│ Output Speed    62.4 tok/s (p50)                                │
╰─────────────────────────────────────────────────────────────────╯

         Tool Usage for claude-sonnet-4-5
┏━━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Tool   ┃ Calls ┃ Success ┃ Failed ┃ Success Rate ┃
┡━━━━━━━━╇━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━┩
│ read   │   620 │     598 │     22 │         96%  │
│ edit   │   412 │     389 │     23 │         94%  │
│ bash   │   298 │     285 │     13 │         96%  │
└────────┴───────┴─────────┴────────┴──────────────┘

Features: - 🔍 Fuzzy Matching - Partial name matches; shows alternatives when multiple models match - 📋 Key-Value Panel - First/last used, sessions, days active, interactions, full token break