Skip to main content

​
Synopsis

Post an entry to a thread without changing ball ownership. Use this when you want to add information while keeping the ball in your court.

​
Usage

watercooler ack <topic> [options]

​
Arguments

​
topic
string
required
Thread topic identifier

​
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
​
--title
string
default:"Ack"
Entry title. Defaults to “Ack” if not provided.
​
--body
string
default:"ack"
Entry body text. Supports markdown. Use @filepath to read from a file. Defaults to “ack”.
​
--type
string
default:"Note"
Entry type. Valid values: Note, Plan, Decision, PR, Closure
​
--status
string
Optional status update for the thread
​
--ball
string
Optional ball ownership update. Note: Does NOT auto-flip like say command.
​
--agents-file
string
Path to agent registry JSON file

​
Examples

​
Simple acknowledgment

watercooler ack feature-auth
Output: 
/home/user/project/watercooler/feature-auth.md
Creates an entry with default title “Ack” and body “ack”.

​
Acknowledgment with custom message

watercooler ack feature-auth \
  --title "Building" \
  --body "Starting implementation, keeping ball."

​
Progress update while keeping ball

watercooler ack api-redesign \
  --title "Progress update" \
  --body "Completed 3 of 5 endpoints. Still working." \
  --role "implementer"

​
Acknowledgment with role specification

watercooler ack feature-auth \
  --title "Reviewing" \
  --body "Spec: implementer\n\nCode review in progress." \
  --role "implementer"

​
Acknowledgment from file

watercooler ack feature-auth \
  --title "Test results" \
  --body "@test-output.txt" \
  --role "tester"

​
Expected Output

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

​
Ball Mechanics

Unlike say, the ack command:
  • Does NOT automatically flip the ball
  • Preserves current ball ownership
  • Can optionally change ball ownership with --ball flag
This makes ack ideal for:
  • Progress updates while still working
  • Acknowledging a message without taking action
  • Adding context without changing ownership

​
Comparison: ack vs say

Featureacksay
Adds entry✓✓
Auto-flips ball✗✓
Title required✗ (default: “Ack”)✓
Body required✗ (default: “ack”)✓
Typical useProgress updates, keeping ballCompleting work, passing ball
  • say - Add entry with automatic ball flip
  • handoff - Explicitly pass the ball
  • set-ball - Update ball ownership only

Build docs developers (and LLMs) love

Get started for freeTalk to us