Skip to main content

​
Synopsis

Display all threads with their current status, ball ownership, last update time, and NEW markers for unread threads.

​
Usage

watercooler list [options]

​
Options

​
--threads-dir
string
Threads directory path. Defaults to ./watercooler or $WATERCOOLER_DIR.
​
--open-only
boolean
Show only threads with status other than “closed”
​
--closed
boolean
Show only closed threads

​
Examples

​
List all threads

watercooler list
Output: 
2024-03-15T14:30:22Z    open        codex       NEW     OAuth Authentication    /path/to/watercooler/feature-auth.md
2024-03-14T09:15:00Z    in_review   human               API Redesign            /path/to/watercooler/api-redesign.md
2024-03-13T16:45:30Z    closed      human               Bug Fix #123            /path/to/watercooler/bug-123.md

​
List only open threads

watercooler list --open-only
Output: 
2024-03-15T14:30:22Z    open        codex       NEW     OAuth Authentication    /path/to/watercooler/feature-auth.md
2024-03-14T09:15:00Z    in_review   human               API Redesign            /path/to/watercooler/api-redesign.md

​
List only closed threads

watercooler list --closed
Output: 
2024-03-13T16:45:30Z    closed      human               Bug Fix #123            /path/to/watercooler/bug-123.md
2024-03-12T11:20:15Z    closed      codex               Performance Optimization /path/to/watercooler/perf-opt.md

​
List threads in custom directory

watercooler list --threads-dir ~/projects/myapp/threads

​
Output Format

Each line contains tab-separated fields: 
<timestamp>    <status>    <ball>    <NEW marker>    <title>    <file path>
FieldDescription
TimestampISO 8601 format, UTC timezone
StatusThread status (e.g., open, closed, in_review, blocked)
BallCurrent ball owner (codex, human, or custom agent name)
NEW markerShows “NEW” if thread has unread updates, empty otherwise
TitleThread title or topic
File pathAbsolute path to thread file

​
NEW Marker

The NEW marker indicates threads with updates since your last access. This helps identify where attention is needed. NEW status is tracked per-user and persists across sessions.

​
Filtering Logic

​
Default (no flags)

Shows all threads regardless of status.

​
—open-only

Excludes threads with status="closed".

​
—closed

Shows only threads with status="closed".

​
Both flags together

watercooler list --open-only --closed
Cancels filtering - equivalent to showing all threads.

​
Common Workflows

​
Morning check-in

# See where you have the ball and what's new
watercooler list --open-only | grep codex

​
Find blocked work

watercooler list --open-only | grep blocked

​
Review completed work

watercooler list --closed

​
Find threads needing attention

watercooler list --open-only | grep NEW

​
Integration with Other Tools

The tab-separated output is designed for easy parsing: 
# Extract just the file paths
watercooler list --open-only | cut -f6

# Count open threads
watercooler list --open-only | wc -l

# Find threads with specific keywords
watercooler list | grep -i "authentication"

Build docs developers (and LLMs) love

Get started for freeTalk to us