tce-monitor 0.4.0

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

TCE - Terminus Cancrorum Est

"The End of the Crab"

A macOS menu bar app + web dashboard + CLI for monitoring Claude Code processes, token usage, and costs.

---

The Problem

Running multiple concurrent Claude Code sessions across many projects leaves you blind:

• No process visibility — How many Claude sessions are running? Which are stuck?
• Zombie and stale processes — Forgotten sessions silently consume hundreds of MBs
• Resource hogs — Claude processes can spike to 75%+ of your system's CPU or memory
• Token cost blindness — Opus 4.5 costs $90/M output tokens. Costs compound invisibly across sessions.
• No session history — Which projects burned the most tokens today?

tce gives you real-time visibility into all of this from a single command, a menu bar icon, or a web dashboard.

Install

pipx install tce-monitor

That's it. On macOS, this automatically includes the menu bar and native webview. On Linux, you get the CLI and web dashboard. Requires Python 3.11+.

To auto-start at login (macOS):

tce install

Don't have pipx? Install it with brew install pipx && pipx ensurepath (macOS) or pip3 install --user pipx (any platform).

Quick Start

# See all your Claude processes with CPU/memory usage
tce status

# Check how much you've spent on tokens
tce usage

# Kill all idle processes
tce kill-stale

# Kill a specific resource-heavy process
tce kill 12345

# Launch the web dashboard
tce dashboard

# Run menu bar app with live monitoring
tce run

---

CLI Reference

Command	Description
tce status	Process health overview — PIDs, projects, memory, CPU, uptime, health status
tce usage	Token usage and costs — per-model breakdown with input, output, cache tokens
tce sessions	Recent session history — project, duration, tokens, lines changed, summary
tce kill <PID>	Kill a Claude process (SIGTERM). Add --force for SIGKILL
tce kill-stale	Find and kill all stale processes at once
tce pin <PID>	Pin a process — exempts it from stale detection
tce unpin <PID>	Remove pin from a process
tce dashboard	Start the web dashboard on localhost:5111 and open in browser
tce dashboard-stop	Stop the running dashboard server
tce run	Full app — menu bar + dashboard (macOS) or dashboard-only (other platforms)
tce install	Install as macOS login service (auto-start at login via launchd)
tce uninstall	Remove macOS login service

Example Output

============================================================
 TERMINUS CANCRORUM EST — Process Status
============================================================
 Total: 7  |  Healthy: 4  |  Stale: 3  |  Zombie: 0  |  Pinned: 0
 Resource Alerts: 1  |  Total Memory: 3449 MB
============================================================
 [+] PID  17742  rpgmaster                      6 MB    0.0%     6.9h  healthy
 [!] PID  31230  crab-trap                    392 MB    0.0%     6.8h  stale
              terminal: /dev/ttys002
 [+] PID  41126  openclaw                     219 MB   82.5%     1.4h  healthy
              ⚠️  RESOURCE ALERT: CPU 82.5% of system
 [+] PID  59593  adventure-graph              953 MB    0.0%     2.3h  healthy
              terminal: /dev/ttys003
 [!] PID  85244  tweek-public                1167 MB    0.0%     6.1h  stale
              terminal: /dev/ttys007

 WARNING: 3 stale process(es) detected. Use 'tce kill-stale' to clean up.
 WARNING: 1 process(es) consuming excessive resources (>75% CPU or memory).

============================================================
 TERMINUS CANCRORUM EST — Token Usage & Costs
============================================================
 Total Cost: $22,248.66
 Total Sessions: 183
============================================================
 Model                     Input     Output   Cache Rd   Cache Cr         Cost
 -------------------- ---------- ---------- ---------- ---------- ------------
 Opus 4.5                   2.9M       8.0M       7.4B     460.4M $ 20,318.33
 Opus 4.6                 392.0K     365.9K     734.6M      41.2M $  1,906.99
 Sonnet 4.5                 4.4K        655      23.6M       2.7M $     17.26
 Haiku 4.5                  5.7K       6.5K      31.4M       3.5M $      6.07
 -------------------- ---------- ---------- ---------- ---------- ------------
 TOTAL                      3.3M       8.3M       8.2B            $ 22,248.66

---

Web Dashboard

Start with tce dashboard and open http://localhost:5111.

Features

Processes Tab

• Live process table with color-coded health dots (green/yellow/red/blue)
• PID, project name, memory, CPU%, uptime, child process count, terminal
• Resource usage: CPU and memory as % of total system (with alert indicators)
• One-click Kill, Force Kill, and Pin/Unpin buttons
• Status badge: "ALL HEALTHY", "STALE DETECTED", "ZOMBIE DETECTED", or "RESOURCE ALERTS"
• Auto-refreshes every 10 seconds

Token Usage Tab

• Cost breakdown by model with color-coded bars
• Stacked bar chart of daily token consumption (last 30 days) via Chart.js
• Detailed token table: input, output, cache read, cache creation per model
• Total cost prominently displayed

Sessions Tab

• Recent sessions sorted by start time
• Project name, start time, duration, input/output tokens
• Lines added/removed (green/red)
• Session summary text

Design

• Dark theme with monospace typography
• Tailwind CSS + Chart.js
• Sticky header with live status badge
• Responsive layout (2-6 column stat cards)

API Endpoints

All data is available programmatically:

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

---

macOS Menu Bar

With pip install 'tce-monitor[macos]', run tce run to get a persistent menu bar icon:

• Menu bar icon: Crab emoji with status badges

  • 🦀 💀2 — 2 zombie processes (highest priority)
  • 🦀 ⚠️1 — 1 resource alert
  • 🦀 🟡3 — 3 stale processes
  • 🦀 — all healthy

• Dropdown menu: All processes with detailed metrics

  • Health icons (✅ healthy, 🟡 stale, 💀 zombie, 📌 pinned)
  • CPU usage with 🔴 red circle when >75% of system
  • Memory usage with 🔴 red circle when >75% of system
  • Uptime in hours
  • Example: ⚠️ ✅ 12345 — my-project (🔴 CPU: 85.0%, Mem: 1024MB, 1.2h)

• Per-process actions: Kill, Force Kill, Pin/Unpin

• Resource alert details: Expand processes with ⚠️ to see system-wide percentages

  • Example: System Usage: 🔴 CPU 82.5%, Memory 6.2%

• Open Dashboard: Launch the web dashboard in a native webview window

• macOS notifications: Alerts when processes go stale, become zombies, or consume excessive resources (with 30-minute cooldown per alert type)

• Summary line: Process count, total memory, and resource alert count

  • Example: 5 processes | 5877 MB total | ⚠️ 2 resource alerts

The menu bar runs on the main thread (required by PyObjC) with the web dashboard on a daemon thread.

Enabling Notifications

Desktop notifications require terminal-notifier (installed automatically by tce install, or manually with brew install terminal-notifier).

After the first notification fires, macOS will silently suppress future alerts unless you allow them:

1. Open System Settings > Notifications > terminal-notifier
2. Toggle Allow Notifications to ON
3. Set alert style to Banners or Alerts

Important: If you use Focus / Do Not Disturb, notifications will be blocked while it's active. Add terminal-notifier to your Focus mode's allowed apps, or notifications will only appear when Focus is off.

---

Process Detection

Claude Code doesn't appear as claude in ps aux. Detection uses two strategies:

Strategy	How
Primary	Executable path contains .local/share/claude/versions/
Fallback	cmdline[0] == 'claude'

Both are checked per-process via psutil, with graceful handling of AccessDenied and NoSuchProcess.

Health Classification

Status	Icon	Criteria
Healthy	+ / green	Running or sleeping, under all thresholds
Stale	! / yellow	Sleeping with <1% CPU for >4h (interactive) or >8h (background)
Zombie	X / red	Process in stopped (T) or zombie (Z) state
Pinned	* / blue	User-exempted from stale detection via tce pin

Interactive vs. background is determined by whether the process has an attached terminal (/dev/ttys*).

Resource Alerts

TCE monitors CPU and memory consumption per process as a percentage of total system resources:

Metric	Threshold (Default)	Alert Trigger
CPU	75% of system	Process using ≥75% of total CPU cores
Memory	75% of system	Process using ≥75% of total RAM

Alert Types:

• HIGH_CPU — Process exceeds CPU threshold
• HIGH_MEMORY — Process exceeds memory threshold
• BOTH — Process exceeds both thresholds

Example: On an 8-core system with 16GB RAM:

• A process using 6+ cores (≥600% in ps terms) triggers HIGH_CPU
• A process using 12+ GB triggers HIGH_MEMORY

Visual Indicators:

• CLI: ⚠️ with exact percentages (⚠️ RESOURCE ALERT: CPU 82.5% of system)
• Menu bar: 🔴 red circles next to exceeding values (🔴 CPU: 85.0%)
• Notifications: macOS alerts with actionable kill suggestions

Independent from health status: A process can be healthy (active) but still trigger resource alerts.

Data Sources

Source	Path	What It Provides
Live processes	psutil	PID, executable, cmdline, cwd, terminal, CPU%, RSS, children
Stats cache	~/.claude/stats-cache.json	Token counts per model, daily activity, session totals
Session meta	~/.claude/usage-data/session-meta/*.json	Per-session: project, duration, tokens, tools used, lines changed, summary

Token data uses mtime-based caching — files are only re-read when modified.

Model Pricing

Costs are computed from Anthropic's published pricing (per million tokens):

Model	Input	Output	Cache Read	Cache Creation
Opus 4.5	$15.00	$75.00	$1.50	$18.75
Opus 4.6	$15.00	$75.00	$1.50	$18.75
Sonnet 4.5	$3.00	$15.00	$0.30	$3.75
Haiku 4.5	$0.80	$4.00	$0.08	$1.00

---

Configuration

Settings are loaded from environment variables (with CLAUDE_MONITOR_ prefix) and .env files:

Variable	Default	Description
CLAUDE_MONITOR_PORT	5111	Dashboard server port
CLAUDE_MONITOR_HOST	127.0.0.1	Dashboard bind address
CLAUDE_MONITOR_PROCESS_POLL_INTERVAL	10	Seconds between process scans
CLAUDE_MONITOR_STALE_INTERACTIVE_HOURS	4.0	Hours before interactive process is stale
CLAUDE_MONITOR_STALE_BACKGROUND_HOURS	8.0	Hours before background process is stale
CLAUDE_MONITOR_STALE_CPU_THRESHOLD	1.0	CPU% below which a process is considered idle
CLAUDE_MONITOR_RESOURCE_CPU_PERCENT_THRESHOLD	75.0	CPU% of system before resource alert
CLAUDE_MONITOR_RESOURCE_MEMORY_PERCENT_THRESHOLD	75.0	Memory% of system before resource alert
CLAUDE_MONITOR_ALERT_COOLDOWN	1800	Seconds between macOS alerts for same PID
CLAUDE_MONITOR_RESOURCE_ALERT_COOLDOWN	1800	Seconds between resource alerts for same PID

Auto-Start at Login (macOS)

The easiest way to have TCE start automatically when you log in:

tce install

This creates a macOS launchd service that:

• Starts tce run (menu bar + dashboard) at every login
• Keeps the process alive (auto-restarts if it crashes)
• Logs to ~/.terminus-cancrorum-est/logs/

To remove:

tce uninstall

Manual launchd Setup

If you prefer to manage the plist yourself:

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

---

Claude Code Skill Integration

TCE includes a Claude Code skill so any Claude session can query your processes. Drop this project in your workspace and Claude will automatically use it:

You: "Check my Claude processes"
Claude: [runs tce status] → reports 7 processes, 3 stale

You: "How much have I spent on Claude?"
Claude: [runs tce usage] → $22,248.66 total, Opus 4.5 dominant

You: "Kill stale processes"
Claude: [runs tce kill-stale] → killed 3 processes

The skill is defined in .claude/skills/terminus-cancrorum-est/SKILL.md.

---

Development

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

# Run tests
pytest tests/ -v --cov=tce

# Lint
ruff check tce/ tests/

# Type check
mypy tce/

Project Structure

Terminus-Cancrorum-Est/
├── tce/                          # Installable Python package
│   ├── cli.py                    # CLI entry point (tce command)
│   ├── app.py                    # Full app: menu bar + dashboard
│   ├── menubar.py                # rumps macOS menu bar
│   ├── dashboard.py              # FastAPI web dashboard
│   ├── webview_window.py         # Native webview (macOS, optional)
│   ├── process_scanner.py        # psutil process detection + health
│   ├── token_tracker.py          # Stats cache + session meta parsing
│   ├── cost_calculator.py        # Token → USD pricing
│   ├── alert_service.py          # macOS notification alerts
│   ├── models.py                 # Pydantic models
│   ├── config.py                 # pydantic-settings configuration
│   ├── templates/
│   │   └── dashboard.html        # Tailwind + Chart.js dashboard
│   └── static/
│       └── logo.jpg
├── tests/                        # 50 tests (pytest)
│   ├── test_process_scanner.py   # Detection, health, pinning, scan, kill
│   ├── test_token_tracker.py     # Dashboard assembly, sessions, caching
│   ├── test_cost_calculator.py   # Pricing accuracy per model
│   └── test_models.py            # Pydantic serialization
├── scripts/
│   └── com.terminus-cancrorum-est.plist   # launchd auto-start
├── pyproject.toml                # Package metadata + tool config
├── LICENSE                       # MIT
└── README.md

Architecture

tce run
├── Main thread: rumps menu bar [macOS only, requires pip install tce-monitor[macos]]
│   ├── Crab icon with zombie/stale badge
│   ├── Process dropdown with Kill/Pin actions
│   ├── "Open Dashboard" → native webview subprocess
│   └── macOS notification alerts (stale/zombie)
│
└── Daemon thread: FastAPI + uvicorn on :5111
    ├── GET /                  → Tailwind dashboard (Jinja2 template)
    ├── GET /api/processes     → ProcessScanner.scan()
    ├── GET /api/usage         → TokenTracker.get_dashboard()
    ├── GET /api/sessions      → TokenTracker.get_recent_sessions()
    ├── POST /api/kill/{pid}   → ProcessScanner.kill_process()
    └── POST /api/pin/{pid}    → ProcessScanner.pin()

On non-macOS platforms (or without the [macos] extra), tce run launches the dashboard on the main thread instead.

---

Platform Support

Platform	tce CLI	Web Dashboard	Menu Bar	Native Webview	Notifications
macOS	Yes	Yes	Yes (with [macos])	Yes (with [macos])	Yes
Linux	Yes	Yes	No	No	No
Windows	Untested	Probably	No	No	No

---

License

MIT — Tommy Mancino, 2026