wooster

An htop-style monitor for AI coding agents. Built for Claude Code and Codex, it also works with other CLI agents (custom).

If you're running multiple coding agents across terminal sessions, it gets hard to tell which ones are still working, which ones went idle, and which ones need attention. 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 and Linux)
• 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

# Install as a CLI tool
uv tool install git+https://github.com/duriantaco/wooster.git

# or
pipx install git+https://github.com/duriantaco/wooster.git

# Just run it. Auto-discovers everything
wooster

# htop-style
wooster top

# Continuous monitoring (refreshes every 2s)
wooster watch

For local development:

pip install -e .

Usage

Monitoring

# 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

# 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

# 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)

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:

{
  "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 /proc/<pid>/cwd on Linux and a batched lsof call on macOS.

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

Notifications fire once when an agent transitions to idle or exits. On macOS, Wooster uses osascript; on Linux, it uses notify-send when available. 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)

Idle agents sort to the top.

Requirements

• Python 3.8+
• macOS or Linux
• Terminal with Unicode support

Validation

• Linux process discovery is validated on a real Ubuntu 24.04 runtime
• A cross-platform CI workflow is included for macOS and Ubuntu
• A manual Linux desktop checklist for notifications and terminal titles lives in docs/linux-desktop-test-plan.md

License

MIT