docsInstallation

Installation

Prerequisites

Before installing OpenCode Monitor, ensure you have:

  • Python 3.8+ installed on your system
  • pip package manager (or pipx for isolated installs)
  • OpenCode AI installed and configured

Method 1: pipx Installation (Recommended)

pipx is the recommended way to install OpenCode Monitor. It creates isolated Python environments and is the safest option across all platforms.

Advantages:

  • No dependency conflicts with system packages
  • Works on Arch Linux, Ubuntu, macOS, Windows
  • No sudo required
  • Easy to upgrade, uninstall, or manage multiple versions
  • Automatically adds ocmonitor to your PATH
# Clone the repository
git clone https://github.com/Shlomob/ocmonitor-share.git
cd ocmonitor-share
 
# Install with pipx (recommended)
pipx install .
 
# Or with optional extras:
pipx install ".[charts]"    # Includes plotly for visualization
pipx install ".[export]"    # Includes pandas for data export
pipx install ".[charts,export]"  # All extras

Installing pipx:

  • Arch Linux: sudo pacman -S python-pipx
  • Ubuntu/Debian: sudo apt install pipx
  • macOS: brew install pipx
  • Other: python3 -m pip install --user pipx

Method 2: Automated Installation (Linux/macOS)

For Linux and macOS users who prefer a traditional virtual environment setup:

# Clone the repository
git clone https://github.com/Shlomob/ocmonitor-share.git
cd ocmonitor-share
 
# Run the automated installer
./install.sh

The installer will:

  • Check Python version compatibility (3.8+)
  • Create a virtual environment
  • Install all required dependencies from pyproject.toml
  • Configure PATH settings automatically
  • Verify the installation

Method 3: Manual Installation

For development or custom setups:

# Clone the repository
git clone https://github.com/Shlomob/ocmonitor-share.git
cd ocmonitor-share
 
# Install Python dependencies
python3 -m pip install -r requirements.txt
 
# Install the package in development mode
python3 -m pip install -e ".[dev,charts,export]"

Note: The project uses pyproject.toml for modern Python packaging. All dependencies are properly declared and will be installed automatically.

Verify Installation

After installation, verify everything works:

# Check if ocmonitor is accessible
ocmonitor --version
ocmonitor --help
 
# Test with sample data
ocmonitor sessions test_sessions/
 
# Verify configuration
ocmonitor config show

Troubleshooting pipx installs: If ocmonitor command is not found after pipx install:

# Ensure pipx PATH is set up
pipx ensurepath
 
# Or manually add to your shell profile (~/.bashrc, ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

Configuration Setup

After installation, set up your personal configuration:

# Create configuration directory
mkdir -p ~/.config/ocmonitor
 
# Copy default configuration (if available in project)
cp config.toml ~/.config/ocmonitor/config.toml
 
# Or create a new configuration file
touch ~/.config/ocmonitor/config.toml
 
# Edit your configuration
nano ~/.config/ocmonitor/config.toml

Your configuration file should contain:

[paths]
messages_dir = "~/.local/share/opencode/storage/message"
export_dir = "./exports"
 
[ui]
table_style = "rich"
progress_bars = true
colors = true

PATH Configuration (If Needed)

If you get “command not found” errors:

# Find your Python user base
python3 -m site --user-base
 
# Add to your shell profile (~/.bashrc or ~/.zshrc)
export PATH="$(python3 -m site --user-base)/bin:$PATH"
 
# Reload your shell
source ~/.bashrc  # or ~/.zshrc
Quick StartBasic Usage