tce-monitor 0.1.0

Terminus Cancrorum Est — monitor Claude Code processes, token usage, and costs

Terminus Cancrorum Est

"The End of the Crab" — a menu bar app + web dashboard for monitoring Claude Code processes, token usage, and costs.

Install

pip install tce-monitor           # CLI + dashboard (any platform)
pip install tce-monitor[macos]    # + menu bar + native webview (macOS only)

For local development:

git clone https://github.com/tmancino/Terminus-Cancrorum-Est.git
cd Terminus-Cancrorum-Est
pip install -e ".[macos,dev]"

Usage

tce status          # Process health overview
tce usage           # Token usage & costs per model
tce sessions        # Recent session history
tce kill <PID>      # Kill a process (--force for SIGKILL)
tce kill-stale      # Kill all stale processes
tce pin <PID>       # Pin process (exempt from stale detection)
tce unpin <PID>     # Unpin process
tce dashboard       # Start web dashboard on :5111
tce dashboard-stop  # Stop the dashboard
tce run             # Full app: menu bar + dashboard (macOS) or dashboard-only

Why?

Running 6+ concurrent Claude Code sessions across 25+ projects with no visibility into:

• Process health and memory usage
• Zombie/stale processes consuming resources
• Token costs across models
• Session activity history

No existing tool monitors Claude Code processes. This fills that gap.

Architecture

Single Python process
├── Main thread: rumps menu bar (polls every 10s)  [macOS only]
│   ├── Color-coded dot (green/yellow/red) + session count
│   ├── Process dropdown with kill/pin actions
│   └── "Open Dashboard" → browser
└── Daemon thread (or main thread on non-macOS): FastAPI on :5111
    ├── Process table with health indicators
    ├── Token usage charts (Chart.js)
    ├── Cost breakdown per model
    └── Recent sessions list

Shared ProcessScanner and TokenTracker instances used by both interfaces.

On non-macOS platforms (or when rumps is not installed), tce run launches the dashboard on the main thread.

Process Detection

Claude Code doesn't appear as "claude" in ps. Detection uses:

• Primary: p.exe() path contains .local/share/claude/versions/
• Fallback: p.cmdline()[0] == 'claude'

Health Classification

Status	Criteria
Healthy	Running/sleeping, under thresholds
Stale	Sleeping + >4h (interactive) or >8h (background) with <1% CPU
Zombie	Stopped (T) or zombie (Z) state
Pinned	User-exempted from stale detection

Data Sources

Source	Path	Data
Processes	psutil	PID, CPU%, RSS, cwd, terminal, children
Stats cache	~/.claude/stats-cache.json	Token breakdown per model, daily activity
Session meta	~/.claude/usage-data/session-meta/*.json	Per-session tokens, duration, tools, summary

Dashboard

Open http://localhost:5111 or click "Open Dashboard" in the menu bar.

Features

• Processes tab: Live process table with health dots, memory, CPU, uptime, kill/pin buttons
• Token Usage tab: Cost breakdown per model, daily token chart (Chart.js), detailed token table
• Sessions tab: Recent sessions with project, duration, tokens, lines changed, summary

API Endpoints

Method	Path	Description
GET	/	Dashboard HTML
GET	/api/processes	Process list JSON
GET	/api/usage	Token usage + costs JSON
GET	/api/sessions?limit=20	Recent sessions JSON
POST	/api/kill/{pid}?force=false	Kill a process
POST	/api/pin/{pid}	Pin a process
POST	/api/unpin/{pid}	Unpin a process

launchd (Auto-start)

cp scripts/com.terminus-cancrorum-est.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.terminus-cancrorum-est.plist

To stop:

launchctl unload ~/Library/LaunchAgents/com.terminus-cancrorum-est.plist

Configuration

Environment variables (in .env):

Variable	Default	Description
CLAUDE_MONITOR_PORT	5111	Dashboard port

Settings in tce/config.py control polling intervals, health thresholds, and model pricing.

Testing

pip install -e ".[dev]"
pytest tests/ -v --cov=tce

Project Structure

Terminus-Cancrorum-Est/
├── tce/
│   ├── cli.py               # CLI entry point (`tce` command)
│   ├── app.py               # Full app: rumps + FastAPI (or dashboard-only)
│   ├── menubar.py            # rumps menu bar (macOS)
│   ├── dashboard.py          # FastAPI web dashboard
│   ├── webview_window.py     # Native webview (macOS, optional)
│   ├── process_scanner.py    # psutil detection + health
│   ├── token_tracker.py      # Stats + session parsing
│   ├── cost_calculator.py    # Model pricing
│   ├── alert_service.py      # macOS notifications
│   ├── models.py             # Pydantic models
│   ├── config.py             # Settings
│   ├── templates/
│   │   └── dashboard.html    # Tailwind + Chart.js
│   └── static/
│       └── logo.jpg
├── scripts/
│   └── com.terminus-cancrorum-est.plist
├── tests/
└── logs/