📊 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
• 📊 Model Analytics - Detailed breakdown of usage per AI model with --breakdown flag
• 📋 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.)

🎨 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

📤 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

🚀 Quick Start

Installation

Option 1: uv Installation (Fastest - One-liner)

uv is a fast Python package manager. It installs the tool in an isolated environment without cloning the repository.

# Install directly from GitHub
uv tool install git+https://github.com/Shlomob/ocmonitor-share.git

# With optional extras
uv tool install "git+https://github.com/Shlomob/ocmonitor-share.git#egg=ocmonitor[charts,export]"

Why uv?

• No need to clone the repository
• Lightning-fast dependency resolution
• Creates isolated environments automatically
• Easy to upgrade: uv tool upgrade ocmonitor

Option 2: pipx Installation (Cross Platform)

pipx is the recommended way to install Python CLI applications. It creates isolated environments and works on all platforms (including Arch Linux, Ubuntu, macOS, etc.).

git clone https://github.com/Shlomob/ocmonitor-share.git
cd ocmonitor-share
pipx install .

Why pipx?

• Creates isolated environments (no dependency conflicts)
• Works on Arch Linux without breaking system packages
• No sudo required
• Easy to upgrade or uninstall

Optional extras:

# With visualization charts
pipx install ".[charts]"

# With export functionality  
pipx install ".[export]"

# With all extras
pipx install ".[charts,export]"

Option 3: Automated Installation (Linux/macOS)

git clone https://github.com/Shlomob/ocmonitor-share.git
cd ocmonitor-share
./install.sh

Option 4: Manual Installation

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

Basic Usage

# Quick configuration check
ocmonitor config show

# Analyze your sessions (light theme)
ocmonitor --theme light sessions ~/.local/share/opencode/storage/message

# Analyze by project
ocmonitor projects ~/.local/share/opencode/storage/message

# Real-time monitoring (dark theme)
ocmonitor --theme dark live ~/.local/share/opencode/storage/message

# Export your data
ocmonitor export sessions ~/.local/share/opencode/storage/message --format csv

📖 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 ~/.local/share/opencode/storage/message

# Sessions without grouping (flat list)
ocmonitor sessions ~/.local/share/opencode/storage/message --no-group

# 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 ~/.local/share/opencode/storage/message

# Weekly breakdown with per-model breakdown
ocmonitor weekly ~/.local/share/opencode/storage/message --breakdown

# Monthly breakdown
ocmonitor monthly ~/.local/share/opencode/storage/message

# Weekly with custom start day
ocmonitor weekly ~/.local/share/opencode/storage/message --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 5 seconds)
ocmonitor live ~/.local/share/opencode/storage/message

# Custom refresh interval (in seconds)
ocmonitor live ~/.local/share/opencode/storage/message --refresh 10

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

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

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

⚙️ Configuration

Configuration File Location

Create your configuration file at: ~/.config/ocmonitor/config.toml

# Create the configuration directory
mkdir -p ~/.config/ocmonitor

# Create your configuration file
touch ~/.config/ocmonitor/config.toml

Configuration Options

The tool is highly configurable through the config.toml file:

[paths]
messages_dir = "~/.local/share/opencode/storage/message"
export_dir = "./exports"

[ui]
table_style = "rich"
progress_bars = true
colors = true

[export]
default_format = "csv"
include_metadata = true

Configuration File Search Order:

1. ~/.config/ocmonitor/config.toml (recommended user location)
2. config.toml (current directory)
3. Project directory fallback

🛠️ Development

Prerequisites

• Python 3.8+
• pip package manager

Setting Up Development Environment

The project uses pyproject.toml for modern Python packaging. You can install in development mode using either pip or pipx:

git clone https://github.com/Shlomob/ocmonitor-share.git
cd ocmonitor-share

# Using pip (editable install)
python3 -m pip install -e ".[dev]"

# Or using pipx (editable install)
pipx install -e ".[dev]"

Install all extras for development:

python3 -m pip install -e ".[dev,charts,export]"

Running Tests

# Run all tests
pytest

# Run only unit tests
pytest -m unit

# Run only integration tests
pytest -m integration

# Legacy test scripts
python3 test_basic.py
python3 test_simple.py

Project Architecture

ocmonitor/
├── ocmonitor/              # Core package
│   ├── cli.py             # Command-line interface
│   ├── config.py          # Configuration management
│   ├── models/            # Pydantic data models
│   │   ├── session.py     # Session and interaction models
│   │   └── workflow.py    # Workflow grouping models
│   ├── services/          # Business logic services
│   │   ├── agent_registry.py    # Agent type detection
│   │   ├── session_grouper.py   # Workflow grouping logic
│   │   ├── live_monitor.py      # Real-time monitoring
│   │   └── report_generator.py  # Report generation
│   ├── ui/                # Rich UI components
│   │   └── dashboard.py   # Live dashboard UI
│   └── utils/             # Utility functions
│       └── file_utils.py  # File processing
├── config.toml            # User configuration
├── models.json            # AI model pricing data
└── test_sessions/         # Sample test data

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details on:

• 🐛 Reporting bugs
• 💡 Suggesting features
• 🔧 Setting up development environment
• 📝 Code style and standards
• 🚀 Submitting pull requests

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🏆 Acknowledgments

• OpenCode - For creating an excellent AI coding agent that makes development more efficient
• ccusage - A similar monitoring tool for Claude Code that inspired features in this project
• Click - Excellent CLI framework
• Rich - Beautiful terminal formatting
• Pydantic - Data validation and settings

🚀 Status

🧪 Beta Testing - This application is currently in beta testing phase. Please report any issues you encounter.

---

Built with ❤️ for the OpenCode community