Skip to main content

​
Synopsis

Transfer ball ownership without adding an entry. Directly updates thread metadata.

​
Usage

watercooler set-ball <topic> <ball> [options]

​
Arguments

​
topic
string
required
Thread topic identifier
​
ball
string
required
New ball owner. Common values: codex, human, or custom agent name

​
Options

​
--threads-dir
string
Threads directory path. Defaults to ./watercooler or $WATERCOOLER_DIR.

​
Examples

​
Transfer to human

watercooler set-ball feature-auth human
Output: 
/home/user/project/watercooler/feature-auth.md

​
Transfer to codex

watercooler set-ball api-redesign codex

​
Transfer to custom agent

watercooler set-ball feature-auth planner-agent

​
Update ball in custom directory

watercooler set-ball feature-auth human --threads-dir ~/projects/myapp/threads

​
Common Ball Values

Ball ValueTypical Use
codexAI agent has control
humanHuman developer has control
planner-agentSpecific named agent
reviewerWaiting for review
pmProject manager has ball

​
Expected Output

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

​
Side Effects

​
Metadata Updates

  • Updates ball field in YAML frontmatter
  • Updates last_updated timestamp to current time
  • Rewrites thread projection file

​
Git Sync

  • Triggers automatic git commit (if threads directory is a git repository)
  • Commit message: "Update ball: feature-auth -> human"

​
Ball Transfer Methods

Different ways to change ball ownership:

​
1. set-ball (silent transfer)

watercooler set-ball feature-auth human
  • No entry added
  • Direct metadata update
  • Quick ownership change

​
2. say (auto-flip)

watercooler say feature-auth \
  --title "Implementation complete" \
  --body "Ready for review."
  • Adds entry
  • Automatically flips ball to counterpart
  • Documents the handoff

​
3. handoff (explicit transfer with message)

watercooler handoff feature-auth \
  --note "Design approved. Ready to implement."
  • Adds handoff entry
  • Explicit ball transfer
  • Best for clear transitions

​
4. ack (keep ball)

watercooler ack feature-auth \
  --title "Working on it" \
  --body "Still in progress."
  • Adds entry
  • Ball stays with current owner
  • No transfer

​
Comparison Table

MethodAdds EntryBall ChangeUse Case
set-ball✗DirectQuick correction
say✓Auto-flipComplete work, pass ball
handoff✓ExplicitClean transition
ack✓NoneKeep working

​
Workflows

​
Correct ball ownership

# Ball incorrectly assigned
watercooler set-ball feature-auth human

​
Multi-agent coordination

# Assign to specific reviewer
watercooler set-ball feature-auth reviewer-agent

# Return to implementer
watercooler set-ball feature-auth implementer-agent

​
Emergency takeover

# Human takes over from stuck agent
watercooler set-ball stuck-thread human

​
Batch ball updates

# Return all balls to human for weekend
for topic in $(watercooler list --open-only | grep codex | cut -f5); do
  watercooler set-ball "$topic" human
done

​
Query Ball Status

# List threads by ball owner
watercooler list | grep codex
watercooler list | grep human

# Count threads per owner
watercooler list | cut -f3 | sort | uniq -c

# Find your threads (where you have the ball)
watercooler list --open-only | grep "$(whoami)"

​
Ball Mechanics

The ball represents who should act next:
  • Ball with codex: AI agent should respond or take action
  • Ball with human: Human developer should respond or take action
  • Ball with specific agent: That agent is responsible for next action

​
Best Practices

​
Use handoff for documented transfers

# Better (documented)
watercooler handoff feature-auth --note "Ready for review"

# Worse (no context)
watercooler set-ball feature-auth reviewer

​
Use set-ball for corrections

# Ball was set incorrectly, fix it quietly
watercooler set-ball feature-auth codex

​
Use say for natural workflow

# Complete work and pass ball with context
watercooler say feature-auth \
  --title "Implementation done" \
  --body "PR #42 ready for review."
# Ball auto-flips with documented reason

​
Error Handling

​
Thread not found

watercooler set-ball nonexistent human
Error: 
Error: Thread not found: nonexistent
Solution: Verify thread exists with watercooler list.
  • handoff - Explicit ball transfer with entry
  • say - Add entry with auto ball-flip
  • ack - Add entry without ball change
  • set-status - Update thread status
  • list - List threads with ball ownership

Build docs developers (and LLMs) love

Get started for freeTalk to us