Skip to main content

​
Synopsis

Post an entry to a thread and automatically flip the ball to your counterpart. This is the primary command for adding content to threads.

​
Usage

watercooler say <topic> --title <title> --body <body> [options]

​
Arguments

​
topic
string
required
Thread topic identifier

​
Required Options

​
--title
string
required
Entry title (brief summary of the entry)
​
--body
string
required
Entry body text. Supports markdown. Use @filepath to read content from a file.

​
Optional Parameters

​
--threads-dir
string
Threads directory path. Defaults to ./watercooler or $WATERCOOLER_DIR.
​
--agent
string
Agent name. Defaults to “Team” if not specified.
​
--role
string
Agent role. Valid values: planner, critic, implementer, tester, pm, scribe
​
--type
string
default:"Note"
Entry type. Valid values:
  • Note - General message or status update (default)
  • Plan - Design or approach proposal
  • Decision - Resolved choice
  • PR - Pull request reference
  • Closure - Thread conclusion
​
--status
string
Optional status update for the thread (e.g., open, blocked, closed)
​
--ball
string
Explicit ball owner override. By default, the ball auto-flips to counterpart.
​
--agents-file
string
Path to agent registry JSON file for agent metadata

​
Examples

​
Basic entry

watercooler say feature-auth \
  --title "Implementation complete" \
  --body "Auth module implemented with OAuth2 support."

​
Entry with role and type

watercooler say feature-auth \
  --title "PR ready for review" \
  --body "PR #42 implements the authentication flow." \
  --role "implementer" \
  --type "PR"

​
Entry from file

watercooler say feature-auth \
  --title "Design document" \
  --body "@docs/auth-design.md" \
  --type "Plan"

​
Update status with entry

watercooler say api-redesign \
  --title "Implementation blocked" \
  --body "Waiting for upstream API changes." \
  --status "blocked"

​
Specify agent and keep ball

watercooler say feature-auth \
  --title "Starting implementation" \
  --body "Beginning work on auth module." \
  --agent "Claude" \
  --role "implementer" \
  --ball "codex"

​
Expected Output

The command prints the path to the updated thread file: 
/home/user/project/watercooler/feature-auth.md

​
Ball Mechanics

By default, say automatically flips the ball to your counterpart:
  • If the ball was with codex, it moves to human
  • If the ball was with human, it moves to codex
To override this behavior, use the --ball flag explicitly.
  • ack - Acknowledge without flipping the ball
  • handoff - Explicitly pass the ball with a message
  • set-status - Update thread status only
  • read-thread - Read thread content (MCP tool)

Build docs developers (and LLMs) love

Get started for freeTalk to us