wooster 0.1.0__tar.gz

wooster-0.1.0/.claude/settings.local.json

@@ -0,0 +1,40 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python3 -c \"import rich; print\\(rich.__version__\\)\")",
+      "Bash(python3 -c \"import sqlite3; print\\(''sqlite3 ok''\\)\")",
+      "Bash(chmod:*)",
+      "Bash(./agents add:*)",
+      "Bash(./agents list:*)",
+      "Bash(./agents todo:*)",
+      "Bash(./agents done:*)",
+      "Bash(./agents show:*)",
+      "Bash(./agents clear:*)",
+      "Bash(rm -f ~/.agents/agents.db)",
+      "Bash(python3 agents:*)",
+      "Bash(./agents)",
+      "Bash(./agents -v)",
+      "Bash(./agents --help)",
+      "Bash(ps -eo pid,state,wchan,command)",
+      "Bash(ps -eo pid,wmesg,command)",
+      "Bash(ps -eo pid,tty,state,command)",
+      "Bash(ps -eo pid,ppid,state,command)",
+      "Bash(ps -eo pid,ppid,state,%cpu,command)",
+      "Bash(for pid:*)",
+      "Bash(do echo:*)",
+      "Bash(done)",
+      "Bash(pip install:*)",
+      "Bash(python:*)",
+      "Bash(python3 -m nestor.cli clear)",
+      "Bash(nestor scan:*)",
+      "Bash(nestor bar:*)",
+      "Bash(nestor:*)",
+      "Bash(ps -eo pid,tty,command)",
+      "Bash(python3 -m nestor.cli)",
+      "Bash(echo \"EXIT: $?\")",
+      "Bash(python3:*)",
+      "Bash(ls /Users/oha/nestor/*.tmp)",
+      "Bash(git -C /Users/oha/nestor status)"
+    ]
+  }
+}

wooster-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+*.db
+.DS_Store
+venv
+.venv
+.tmp
+bin

wooster-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-03-21
+
+### Added
+
+- Initial release
+- CLI entry point with argparse subcommands
+- SQLite database storage at `~/.wooster/wooster.db` with WAL mode
+- **Auto-discovery**: scans `ps` for running Claude Code, Codex, Gemini, Aider, Copilot, Cursor, and GPT CLI processes
+- **Child process deduplication**: filters out subprocess forks, only tracks leader processes
+- **Duplicate numbering**: multiple sessions in the same directory get `#1`, `#2`, etc.
+- **Idle heuristic**: flags likely-idle agents with sleeping state + low CPU + no network activity as `🔔 idle?`
+- **CWD resolution**: uses `lsof` to find the working directory of each agent process
+- **Watch mode**: `wooster watch [-n SECONDS]` for continuous terminal refresh
+- **Manual agent management**: `add`, `update`, `done`, `rm`, `clear`
+- **Todo system**: attach and complete todos per agent
+- **Sorted output**: waiting agents at top, done agents at bottom
+- **Stats bar**: summary counts with timestamp
+- **Emoji icons**: per-type and per-status visual indicators

wooster-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing to Wooster
+
+Thanks for your interest in contributing to Wooster!
+
+## Getting started
+
+```bash
+# Clone the repo
+git clone https://github.com/oha/wooster.git
+cd wooster
+
+# Install uv if you don't have it
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Create a virtual environment and install in dev mode
+uv sync
+
+# Run wooster
+uv run wooster
+```
+
+## Project structure
+
+```
+wooster/
+├── bin/wooster              # Standalone executable (no install needed)
+├── wooster/
+│   ├── __init__.py         # Version string
+│   ├── cli.py              # Argparse setup + command routing
+│   ├── db.py               # SQLite schema, connection, migrations
+│   ├── discovery.py        # Process scanning, waiting detection, DB sync
+│   ├── display.py          # Table formatting, icons, stats bar
+│   └── commands.py         # All subcommand handlers
+├── pyproject.toml          # Project config (uv/hatch)
+├── README.md
+├── CHANGELOG.md
+├── CONTRIBUTING.md
+└── LICENSE
+```
+
+## How it works
+
+1. **`db.py`** — SQLite database at `~/.wooster/wooster.db`. Two tables: `agents` and `todos`. Uses WAL mode for concurrent access.
+
+2. **`discovery.py`** — Scans `ps` output for known AI CLI patterns. Filters child processes, resolves CWDs via `lsof`, detects idle agents (sleeping + <0.5% CPU = waiting for input).
+
+3. **`display.py`** — Formats the agent table with emoji icons, stats bar, and sorted output (waiting first, done last).
+
+4. **`commands.py`** — All subcommand handlers. Each one opens a DB connection, does its thing, and closes.
+
+5. **`cli.py`** — Argparse setup and routing. This is the entry point for both `bin/wooster` and `pip install`.
+
+## Adding a new agent type
+
+1. Add a regex pattern to `AGENT_PATTERNS` in `wooster/discovery.py`
+2. Add an icon to `TYPE_ICON` in `wooster/display.py`
+3. Add the type string to the `--type` choices in `wooster/cli.py`
+
+## Adding a new command
+
+1. Write the handler in `wooster/commands.py`
+2. Add the argparse subparser in `wooster/cli.py`
+3. Add it to the `cmd_map` dict in `wooster/cli.py`
+
+## Code style
+
+- Pure Python 3 stdlib only — no external dependencies
+- Keep it simple, no over-engineering
+- Functions over classes where possible
+- Emoji icons are fine for terminal output
+
+## Submitting changes
+
+1. Fork the repo
+2. Create a branch (`git checkout -b my-feature`)
+3. Make your changes
+4. Test with `uv run wooster` and verify the output looks right
+5. Commit and push
+6. Open a PR
+
+## Reporting bugs
+
+Open an issue at https://github.com/oha/wooster/issues with:
+- What you ran
+- What you expected
+- What happened instead
+- Your OS and Python version (`python3 --version`)

wooster-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wooster-0.1.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: wooster
+Version: 0.1.0
+Summary: CLI to track AI coding agents (Claude Code, Codex, Gemini, etc.) in real time
+Project-URL: Homepage, https://github.com/oha/wooster
+Project-URL: Repository, https://github.com/oha/wooster
+Project-URL: Issues, https://github.com/oha/wooster/issues
+Author: oha
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,claude,cli,codex,gemini,monitoring
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# 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

wooster-0.1.0/README.md

@@ -0,0 +1,209 @@
+# 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

wooster-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "wooster"
+version = "0.1.0"
+description = "CLI to track AI coding agents (Claude Code, Codex, Gemini, etc.) in real time"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+authors = [{ name = "oha" }]
+keywords = ["ai", "agents", "cli", "monitoring", "claude", "codex", "gemini"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: System :: Monitoring",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/oha/wooster"
+Repository = "https://github.com/oha/wooster"
+Issues = "https://github.com/oha/wooster/issues"
+
+[project.scripts]
+wooster = "wooster.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["wooster"]

wooster-0.1.0/wooster/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"