Skip to main content
This guide walks you through creating and managing your first thread in Watercooler, from initialization to collaborative entries.

​
What is a Thread?

A thread is a structured conversation between agents (AI or human) working on a specific topic. Each thread:
  • Has a unique topic identifier (e.g., fix-login-bug)
  • Contains entries from different agents with roles
  • Tracks status (OPEN, CLOSED, ABANDONED)
  • Manages ball ownership (who should respond next)
  • Stores data in both graph format (nodes.jsonl, edges.jsonl) and markdown projection

​
Prerequisites

1
Install Watercooler
2
pip install watercooler
3
Set up your workspace
4
mkdir my-project
cd my-project
export WATERCOOLER_DIR=./threads

​
Initializing a Thread

1
Create your first thread
2
Use the init-thread command with a topic identifier:
3
watercooler init-thread fix-login-bug \
  --title "Fix login authentication bug" \
  --status OPEN \
  --ball codex
4
Parameters:
5
  • topic: Unique identifier (use kebab-case)
  • --title: Human-readable title (optional, defaults to topic)
  • --status: Initial status (default: OPEN)
  • --ball: Who should respond next (default: codex)
    • 6
    Expected Output
    7
    This creates:
    8
    threads/
├── fix-login-bug.md              # Markdown projection
└── graph/
    └── baseline/
        └── threads/
            └── fix-login-bug/
                ├── meta.json      # Thread node
                ├── entries.jsonl  # Entry nodes
                └── edges.jsonl    # Relationships
    9
    Verify the thread
    10
    List all threads to confirm:
    11
    watercooler list --threads-dir ./threads
    12
    Output:
    13
    Updated                   | Status | Ball  | NEW | Title                          | Path
2026-03-06T10:30:00Z     | OPEN   | codex |     | Fix login authentication bug   | fix-login-bug.md

    ​
    Adding Entries

    1
    Say: Quick note with ball flip
    2
    The say command adds an entry and automatically flips the ball to the counterpart:
    3
    watercooler say fix-login-bug \
  --agent "Alice" \
  --role "planner" \
  --title "Analysis: JWT token validation issue" \
  --body "Found that expired tokens are not being rejected. The verify_token() function is missing expiration check."
    4
    This:
    5
  • Adds entry from agent “Alice” with role “planner”
  • Automatically flips ball to “team” (counterpart of current ball owner)
  • Updates both graph and markdown
    • 6
    Available Roles:
    7
  • planner: Designs and plans work
  • implementer: Writes code
  • critic: Reviews and provides feedback
  • tester: Validates functionality
  • pm: Project management
  • scribe: Documentation
    • 8
    Ack: Acknowledge without ball flip
    9
    Use ack when you want to add a note but keep the ball with the current owner:
    10
    watercooler ack fix-login-bug \
  --agent "Bob" \
  --role "implementer" \
  --title "Will fix today" \
  --body "Taking this on, should have a PR ready by EOD"
    11
    Handoff: Explicit ball transfer
    12
    Pass the ball to a specific agent:
    13
    watercooler handoff fix-login-bug \
  --agent "Alice" \
  --note "Ready for review"
    14
    Add entry with file content
    15
    Reference a file using the @ prefix:
    16
    watercooler say fix-login-bug \
  --agent "Bob" \
  --role "implementer" \
  --title "Implementation complete" \
  --body "@./implementation-notes.md"

    ​
    Entry Types

    Specify entry type with --type to categorize your entries:
    • Note (default): General observations or updates
    • Plan: Design decisions and approach
    • Decision: Key architectural or implementation choices
    • PR: Pull request references
    • Closure: Thread resolution summary
    Example: 
    watercooler say fix-login-bug \
  --type Decision \
  --title "Using JWT library v4.0" \
  --body "Decided to upgrade to JWT library v4.0 which has built-in expiration validation"

    ​
    Managing Thread Status

    1
    Update status
    2
    # Mark as closed
watercooler set-status fix-login-bug CLOSED

# Other status options: OPEN, BLOCKED, ABANDONED
watercooler set-status fix-login-bug BLOCKED
    3
    Transfer ball ownership
    4
    watercooler set-ball fix-login-bug team

    ​
    Viewing Thread Contents

    1
    Read the markdown file
    2
    cat threads/fix-login-bug.md
    3
    Search threads
    4
    Search across all thread entries:
    5
    watercooler search "JWT" --threads-dir ./threads
    6
    Generate HTML index
    7
    Create a browsable HTML index:
    8
    watercooler web-export --threads-dir ./threads
open threads/index.html

    ​
    Graph-First Architecture

    Watercooler uses a graph-first approach where all writes go to the graph first:
    1. Write to graph: Data is written to nodes.jsonl and edges.jsonl
    2. Project to markdown: The .md file is generated from the graph
    3. Single source of truth: Graph is canonical, markdown is a derived view
    This enables:
    • Semantic search with embeddings
    • Relationship queries
    • Cross-thread references
    • LLM-powered summaries
    See the Memory Graphs guide for details.

    ​
    Next Steps

    Multi-Agent Workflows

    Learn how to orchestrate multiple agents working together

    Branch Pairing

    Sync threads with Git branches for feature work

    Memory Graphs

    Build knowledge graphs from your threads

    Slack Integration

    Get notifications in Slack channels

    ​
    Common Patterns

    ​
    Planning → Implementation → Review

    # 1. Planner analyzes
watercooler say feature-x --role planner \
  --title "Design approach" --body "@design.md"

# 2. Implementer builds
watercooler say feature-x --role implementer \
  --title "Implementation complete" --body "@impl.md"

# 3. Critic reviews
watercooler say feature-x --role critic \
  --title "Review feedback" --body "Looks good, minor suggestions"

# 4. Close when done
watercooler set-status feature-x CLOSED

    ​
    Using Agent Registry

    Create an agents file for consistent naming: 
    {
  "agents": {
    "alice": {"name": "Alice", "role": "planner"},
    "bob": {"name": "Bob", "role": "implementer"}
  }
}
    Use it: 
    watercooler say feature-x --agents-file agents.json \
  --agent alice --title "Planning complete"

    ​
    Troubleshooting

    ​
    Lock Issues

    If a thread appears stuck: 
    watercooler unlock fix-login-bug --force

    ​
    Graph Not Available

    If you see “graph not yet built”: 
    watercooler baseline-graph build --threads-dir ./threads

    ​
    List Entries

    Debug thread contents: 
    watercooler baseline-graph list-entries fix-login-bug \
  --threads-dir ./threads

    Build docs developers (and LLMs) love

    Get started for freeTalk to us