Metadata-Version: 2.4
Name: tce-monitor
Version: 0.1.0
Summary: Terminus Cancrorum Est — monitor Claude Code processes, token usage, and costs
Project-URL: Homepage, https://github.com/tmancino/Terminus-Cancrorum-Est
Project-URL: Repository, https://github.com/tmancino/Terminus-Cancrorum-Est
Project-URL: Issues, https://github.com/tmancino/Terminus-Cancrorum-Est/issues
Author-email: Tommy Mancino <tom.mancino@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: claude,claude-code,monitor,process-monitor,token-usage
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: MacOS X
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: uvicorn>=0.30.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: macos
Requires-Dist: pywebview>=5.0; extra == 'macos'
Requires-Dist: rumps>=0.4.0; extra == 'macos'
Description-Content-Type: text/markdown

# Terminus Cancrorum Est

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

## Install

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

For local development:

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

## Usage

```bash
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)

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

To stop:
```bash
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

```bash
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/
```
