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