Skip to main content

​
Synopsis

Create a new thread with specified topic and optional metadata.

​
Usage

watercooler init-thread <topic> [options]

​
Arguments

​
topic
string
required
Thread topic identifier (e.g., feature-auth, bug-login)

​
Options

​
--title
string
Optional title override. If not provided, topic is used as title.
​
--status
string
default:"open"
Initial thread status. Common values: open, blocked, in_review
​
--ball
string
default:"codex"
Initial ball owner (agent who has the ball)
​
--threads-dir
string
Threads directory path. Defaults to ./watercooler or $WATERCOOLER_DIR environment variable.

​
Examples

​
Basic thread initialization

watercooler init-thread feature-auth
Output: 
/path/to/watercooler/feature-auth.md

​
Thread with custom title

watercooler init-thread feature-auth --title "OAuth2 Authentication Design"

​
Thread with specific initial state

watercooler init-thread api-redesign --status "in_review" --ball "human"

​
Thread in custom directory

watercooler init-thread docs-update --threads-dir ~/project/threads

​
Expected Output

The command prints the path to the newly created thread file: 
/home/user/project/watercooler/feature-auth.md
The thread file is created with:
  • YAML frontmatter containing metadata (status, ball, timestamps)
  • Initial thread structure
  • Automatic git commit if the directory is a git repository
  • say - Add an entry and flip the ball
  • list - List all threads
  • set-status - Update thread status
  • set-ball - Update ball ownership

Build docs developers (and LLMs) love

Get started for freeTalk to us