ccusage-team

Claude Code usage analytics with real-time team monitoring and collaboration

npm version NPM Downloads GitHub stars

繁體中文 | πŸ‡ΊπŸ‡Έ English

> Built on top of the excellent [ccusage](https://github.com/ryoppippi/ccusage) by @ryoppippi. Adds team collaboration, live monitoring, and background sync. --- ## Table of Contents - [Requirements](#requirements) - [Installation](#installation) - [Linux / macOS](#linux--macos) - [Windows (Native)](#windows-native) - [Windows with WSL](#windows-with-wsl) - [Quick Start](#quick-start) - [Commands Reference](#commands-reference) - [Team Features](#team-features) - [Setting Up a Team](#setting-up-a-team) - [Joining a Team](#joining-a-team) - [Live Monitoring](#live-monitoring) - [Background Sync Daemon](#background-sync-daemon) - [Configuration](#configuration) - [Troubleshooting](#troubleshooting) --- ## Requirements | Component | Requirement | |-----------|-------------| | Node.js | 20.19.4 or higher | | Claude Code | Any version | | OS | Linux, macOS, Windows 10/11 (native or WSL) | | Network | Required for team features; local reporting works offline | --- ## Installation ### Linux / macOS ```bash npm install -g ccusage-team ``` Verify the installation: ```bash ccusage-team --version ccusage-team daily ``` --- ### Windows (Native) Run these commands in **PowerShell** or **Command Prompt**: ```powershell npm install -g ccusage-team ``` Verify: ```powershell ccusage-team --version ccusage-team daily ``` **Important for Windows users**: Claude Code stores data in `%APPDATA%\Claude\projects`. The tool detects this automatically. If it fails to find your data, set the path explicitly: ```powershell # Set for current session $env:CLAUDE_CONFIG_DIR = "$env:APPDATA\Claude" ccusage-team daily # Set permanently (add to your PowerShell profile) [System.Environment]::SetEnvironmentVariable("CLAUDE_CONFIG_DIR", "$env:APPDATA\Claude", "User") ``` --- ### Windows with WSL You have two options: **Option A β€” Install inside WSL (Recommended for team sync)** Open your WSL terminal and install there: ```bash # Inside WSL npm install -g ccusage-team ``` Since Claude Code runs natively on Windows (storing data in `%APPDATA%\Claude`), you need to tell the tool where to look. Your Windows username may differ from your WSL username. ```bash # Find your Windows username ls /mnt/c/Users/ # Set the path (replace with your actual Windows username) export CLAUDE_CONFIG_DIR=/mnt/c/Users//AppData/Roaming/Claude # Add to ~/.bashrc or ~/.zshrc so it persists across sessions echo 'export CLAUDE_CONFIG_DIR=/mnt/c/Users//AppData/Roaming/Claude' >> ~/.bashrc source ~/.bashrc # Verify data is found ccusage-team daily ``` **Option B β€” Install natively on Windows, run from WSL via interop** ```powershell # In PowerShell npm install -g ccusage-team ``` Then call from WSL: ```bash # From WSL, invoke the Windows-installed command ccusage-team.cmd daily ``` > For team sync daemons, Option A (WSL-native install) is recommended because daemon process management works reliably on Linux. --- ## Quick Start After installation, you can use the full command or the short alias `ccul`: ```bash # Show today's usage ccusage-team daily # Interactive menu (easiest way to explore all features) ccusage-team ``` --- ## Commands Reference ### Usage Reports ```bash ccusage-team daily # Daily token usage and cost ccusage-team monthly # Monthly aggregated report ccusage-team session # Usage grouped by session ccusage-team blocks # 5-hour billing windows # Short alias ccul daily ccul monthly ccul session ccul blocks ``` ### Report Options ```bash ccul daily --json # Output as JSON ccul daily --mode calculate # Force recalculate cost from tokens ccul daily --mode display # Use pre-calculated cost only ccul daily --since 20250101 # Filter from date (YYYYMMDD) ccul blocks --active # Show current active block only ccul blocks --recent # Show blocks from last 3 days ccul session --project myproject # Filter by project name ``` ### Interactive Menu ```bash ccusage-team # Launch full interactive menu ``` The interactive menu provides access to all features with guided prompts β€” recommended for new users. ### Team Management ```bash ccul team create "Team Name" # Create a new team ccul team join # Join a team with 6-character code ccul team list # List all teams you belong to ccul team members [team-name] # Show team members ccul team usage [team-name] # Show team usage statistics ccul team live [team-name] # Real-time team dashboard ccul team leave # Leave the current team ``` ### Background Sync Daemon ```bash ccul team sync start [team-name] # Start background sync daemon ccul team sync stop [team-name] # Stop the daemon ccul team sync restart [team-name] # Restart the daemon ccul team sync status [team-name] # Show daemon status and last sync ccul team sync once [team-name] # Sync once and exit (one-shot) ccul team sync logs [team-name] # View daemon log output ``` ### Other Commands ```bash ccusage-team update # Check for and apply updates ccusage-team mcp # Start MCP server (stdio) ccusage-team mcp --type http --port 8080 # Start MCP server (HTTP) ``` --- ## Team Features ### Setting Up a Team The team owner creates the team and shares the invite code with members. **Step 1 β€” Create the team:** ```bash ccul team create "My Team" ``` Output example: ``` βœ… Team created successfully Team name: My Team Invite code: ABC123 Share this code with your teammates! ``` **Step 2 β€” Share the invite code** (`ABC123` in this example) with your teammates. --- ### Joining a Team Each team member runs this on their own machine: ```bash ccul team join ABC123 ``` You will be prompted for your display name. Press Enter to accept the system-detected username, or type a custom name: ``` Invite Code: ABC123 User Name: vic ← press Enter to accept, or type a new name ``` After joining, start the sync daemon so your usage data is uploaded automatically: ```bash ccul team sync start ``` --- ### Live Monitoring The team leader or any member can open the live dashboard: ```bash ccul team live ``` The dashboard refreshes every 5 seconds and shows: - **Usage / Current window** β€” your active 5-hour billing block tokens - **Member status (Last 10 days)** β€” each member's cumulative tokens, cost, and activity - **Team total** β€” aggregated team tokens and cost Press `q` or `Ctrl+C` to exit. --- ### Background Sync Daemon The daemon runs in the background and continuously uploads your local usage data to the team database. Without the daemon, your usage won't appear in team statistics. **Start the daemon:** ```bash ccul team sync start # or specify the team explicitly ccul team sync start "My Team" ``` **Check daemon status:** ```bash ccul team sync status ``` Output example: ``` πŸ“Š Sync daemon status β€” My Team Daemon: Running (PID 12345) Last sync: 2026-04-24 10:30:15 Synced blocks: 47 Log file: ~/.config/ccusage-team/daemons/.log ``` **View daemon logs** (most useful for troubleshooting): ```bash ccul team sync logs # Show more lines ccul team sync logs -n 100 ``` **Stop the daemon:** ```bash ccul team sync stop ``` **Sync once without starting the daemon:** ```bash ccul team sync once ``` --- ## Configuration ### Environment Variables | Variable | Description | Example | |----------|-------------|---------| | `CLAUDE_CONFIG_DIR` | Path to Claude data directory | `/mnt/c/Users/vic/AppData/Roaming/Claude` | | `CLICKHOUSE_HOST` | ClickHouse server URL | `https://your-server.com:8443` | | `CLICKHOUSE_DATABASE` | Database name | `ccusage` | | `CLICKHOUSE_USERNAME` | Database username | `default` | | `CLICKHOUSE_PASSWORD` | Database password | `your-password` | ### Multiple Claude Data Directories If you use Claude Code in multiple locations (e.g., both WSL and Windows native), specify all paths comma-separated: ```bash export CLAUDE_CONFIG_DIR="/home/vic/.config/claude,/mnt/c/Users/vic/AppData/Roaming/Claude" ``` --- ## Troubleshooting ### "You have not joined any team" This means the tool can't find your team membership. The user ID is derived from your username and machine information. Check: 1. Make sure you joined the team on this machine with the correct username 2. Run `ccul team list` to see if membership is detected 3. If you joined with a different username, rejoin: `ccul team join ` ### Daemon shows "running" but no data appears in team stats The daemon process may have crashed silently. Check the logs first: ```bash ccul team sync logs ``` **If logs show `ERROR: Cannot find Claude data path`:** Your Claude data directory wasn't found. Set it explicitly: ```bash # For WSL users export CLAUDE_CONFIG_DIR=/mnt/c/Users//AppData/Roaming/Claude # Restart the daemon ccul team sync stop ccul team sync start ``` **If logs show `sync ok β€” ... N failed`:** Data is found but database writes are failing. Check your ClickHouse connection: ```bash # Verify env vars are set echo $CLICKHOUSE_HOST # Run a one-shot sync to see the error details ccul team sync once ``` **If logs show `sync ok β€” ... 0 total blocks`:** Verify that your local usage data exists: ```bash ccusage-team daily ``` If `daily` shows no data either, your `CLAUDE_CONFIG_DIR` points to the wrong location. ### "No valid Claude data directories found" ```bash # Check what paths are being searched ccusage-team daily # Windows: verify the path exists ls "$env:APPDATA\Claude\projects" # PowerShell ls /mnt/c/Users//AppData/Roaming/Claude/projects # WSL # Then set the path explicitly export CLAUDE_CONFIG_DIR=/mnt/c/Users//AppData/Roaming/Claude ``` ### Username not detected correctly on Windows The tool tries `USER` β†’ `USERNAME` β†’ `os.userInfo()` to detect your username. If all fail, run the interactive menu which will prompt you: ```bash ccusage-team # Navigate to: Team Management β†’ Join Team # The prompt will show the detected username; you can override it ``` Or specify manually when running sync commands: ```bash ccul team sync start -u your-name ``` --- ## How It Works 1. Claude Code writes usage data as JSONL files in `~/.config/claude/projects/` (Linux/macOS) or `%APPDATA%\Claude\projects\` (Windows) 2. `ccusage-team` reads these files to generate reports 3. The sync daemon periodically reads the JSONL files and uploads session blocks to a shared ClickHouse database 4. `team live` and `team usage` query this database to show team-wide statistics --- ## Acknowledgements - **[@ryoppippi](https://github.com/ryoppippi)** β€” Creator of the original [ccusage](https://github.com/ryoppippi/ccusage) - **Claude Code Community** β€” For the excellent CLI tool ## License [MIT](LICENSE) Β© [Calderic](https://github.com/Calderic)