# wooster

A process monitor for AI coding agents. Built for **Claude Code** and **Codex**, it also works with other CLI agents (custom).

When you're running multiple agents across terminal sessions, it gets impossible to remember which CLI is doing what, which ones finished, and which ones need your input. Wooster auto-discovers them and gives you a single dashboard.

> **Note:** Idle detection is tuned and tested for Claude Code and Codex. Other agents are auto-detected but the idle/running heuristic may be less accurate. You can also add custom agents via config.

## Features

- **Auto-discovery** — scans running processes for known AI CLIs, no manual setup
- **Smart idle detection** — detects idle agents using child process activity, not just CPU (tuned for Claude Code and Codex)
- **Interactive TUI** — `wooster top` gives you an htop-style monitor with live CPU, memory, process trees, and keybindings to kill/manage agents
- **Desktop notifications** — get notified when an agent goes idle or finishes (macOS)
- **Compact bar mode** — `wooster bar` for tmux status bars or small terminal panes
- **Custom agents** — add your own CLI patterns via `~/.wooster/config.json`
- **Zero dependencies** — pure Python 3, uses only stdlib

## Supported agents

Tested and tuned:

| Type | CLI | Idle detection |
|---|---|---|
| `claude` | `claude` (Claude Code) | accurate |
| `codex` | `codex` (OpenAI Codex CLI) | accurate |

Also auto-detected (idle detection may vary):

| Type | CLI |
|---|---|
| `gemini` | `gemini` (Google Gemini CLI) |
| `aider` | `aider` |
| `copilot` | `github-copilot`, `copilot-cli` |
| `cursor` | `cursor` |
| `gpt` | `sgpt`, `chatgpt` |

## Quick start

```bash
# Install
pip install -e .

# Just run it. Auto-discovers everything
wooster

# htop-style
wooster top

# Continuous monitoring (refreshes every 2s)
wooster watch
```

## Usage

### Monitoring

```bash
# Auto-scan + list all agents (default)
wooster

# Interactive TUI
wooster top # htop for agents
wooster top -n 5 # refresh every 5s

# Continuous watch mode
wooster watch  # refresh every 2s
wooster watch -n 5  # refresh every 5s

# Single-line compact status
wooster bar  # one-shot
wooster bar --watch  # continuous single-line updates

# Raw process scan (verbose debug output)
wooster scan

# Show full detail for an agent
wooster show 3
```

### Managing agents

```bash
# Manually register an agent
wooster add "auth-refactor" -t claude -s "Refactoring auth middleware"
wooster add "auth-refactor" -t claude --status running

# Update an agent
wooster update 3 --summary "Now working on tests"
wooster update 3 -s done
wooster update 3 --name "auth-refactor-v2"

# Mark as done
wooster done 3

# Kill a stuck agent (sends SIGTERM)
wooster kill 3

# Remove an agent from the list
wooster rm 3

# Clear all agents
wooster clear
```

### Todos

```bash
# Add a todo to an agent
wooster todo 3 "Review PR after this finishes"

# Mark a todo as done
wooster todo-done 3 1
```

### tmux integration

Add to your `.tmux.conf` for a status bar showing agent counts:

```
set -g status-right '#(wooster bar)'
set -g status-interval 5
```

## Interactive TUI (`wooster top`)

![wooster top](assets/ss1.png)

An htop-style split-screen monitor:

- **Top half** — agent list with live CPU%, memory, TTY, uptime
- **Bottom half** — process tree for the selected agent showing every subprocess

Keybindings:

| Key | Action |
|---|---|
| `j` / `↓` | Select next agent |
| `↑` | Select previous agent |
| `k` | Kill selected agent (SIGTERM) |
| `d` | Mark selected as done |
| `r` | Remove from list |
| `h` | Toggle showing done agents |
| `q` / `ESC` | Quit |

## Custom agents

Add your own CLI patterns in `~/.wooster/config.json`:

```json
{
  "agents": [
    {"pattern": "my-internal-agent", "type": "custom"},
    {"pattern": "acme-coder", "type": "acme"}
  ],
  "idle_threshold_cpu": 2.0,
  "idle_scans": 3
}
```

- `pattern` — regex matched against the process command line
- `type` — label shown in the type column
- `idle_threshold_cpu` — CPU% below which an agent is considered potentially idle (default: 2.0)
- `idle_scans` — number of consecutive idle scans before flagging as idle (default: 3)

## How it works

### Process discovery

Runs `ps -eo pid,ppid,tty,state,%cpu,lstart,command` and matches against known AI CLI patterns. Child processes (e.g., codex spawning subprocesses) are filtered out so you only see the session leader. CWDs are resolved via a single batched `lsof` call.

### Idle detection

An auto-discovered agent is flagged as `idle?` when all of these are true:

1. Process state is **sleeping** (`S` state)
2. CPU usage is **< 2%**
3. **No active child processes** (non-zombie children doing work)
4. The above conditions persist for **3 consecutive scans** (~6 seconds)

This approach uses child process activity as the primary signal rather than network connections, which proved unreliable due to persistent WebSocket/HTTP2 keep-alive connections.

### PID reuse protection

Agents are tracked by `(PID, process start time)` rather than PID alone, so a recycled PID from a different process won't be confused with the original agent.

### Desktop notifications

macOS notifications fire once when an agent transitions to idle or exits. Notifications are deduplicated — you won't get repeat alerts from brief CPU fluctuations.

### Data storage

Agent state is stored in `~/.wooster/wooster.db` by default (SQLite with WAL mode for safe concurrent access). Override the path with `WOOSTER_DB_PATH`. Old completed agents are auto-pruned after 7 days, capped at 500 entries.

## Output (`wooster` / `wooster watch`)

![wooster watch](assets/ss2.png)

Idle agents sort to the top.

## Requirements

- Python 3.9+
- macOS (uses `ps` and `lsof` for process inspection)
- Terminal with Unicode support

## License

MIT
