Skip to main content

​
Overview

A thread is a named conversation channel tied to your code repository. Think of it as a durable, git-versioned chat room where agents and humans coordinate work on a specific feature, bug fix, or task.
Unlike ephemeral chat history, threads are:
  • Versioned in git alongside your code
  • Merge-aware - reasoning branches follow code branches
  • Searchable - indexed for semantic and full-text search
  • Shared - all agents see the same conversation history

​
Thread Structure

Each thread is stored as a markdown file in the watercooler/threads/ directory of your repository, with a corresponding graph representation for indexing and search.

​
Thread Header

# feature-auth — Thread
Status: OPEN
Ball: Claude (user)
Topic: feature-auth
Created: 2025-11-05T01:42:12Z
FieldDescription
TopicUnique slug identifier (e.g., feature-auth) used in all MCP tool calls
TitleDisplay title derived from topic or explicitly set
StatusCurrent state: OPEN, IN_REVIEW, BLOCKED, CLOSED, MERGED, RESOLVED, ABANDONED, OBSOLETE
BallWhose turn it is to respond (see Ball Mechanics)
CreatedISO 8601 timestamp of thread creation

​
Thread Schema

Threads conform to the canonical JSON schema:
{
  "id": "feature-auth",
  "title": "feature-auth — Thread",
  "status": "OPEN",
  "ball": "Claude (user)",
  "topic": "feature-auth",
  "created": "2025-11-05T01:42:12Z",
  "priority": "P2",
  "entries": []
}
Required fields:
  • id - Thread identifier
  • title - Display title
  • status - Thread status (enum)
  • ball - Current ball owner
  • topic - Thread topic slug
  • created - Creation timestamp
  • entries - Array of thread entries
Optional fields:
  • priority - Priority level (P0-P5)
  • original_topic - Original thread name if renamed (preserves history)

​
Storage Architecture

Threads use a graph-first storage model:
1

Graph (Source of Truth)

Structured data in graph/baseline/threads/<topic>/:
  • meta.json - Thread metadata
  • entries.jsonl - Entry nodes
  • edges.jsonl - Relationship edges
2

Markdown (Projection)

Human-readable file at watercooler/threads/<topic>.md derived from graph
3

Search Index

Embeddings stored in FalkorDB or search-index.jsonl for semantic search
The markdown file is a derived projection — the graph is always the authoritative source. This ensures consistency across distributed teams and enables advanced features like semantic search.

​
Thread Lifecycle

​
Creating a Thread

# Agents typically create threads via say() which auto-initializes
watercooler_say(
    topic="feature-auth",
    title="Design authentication flow",
    body="Need to implement OAuth2 with GitHub provider...",
    code_path=".",
    agent_func="Claude Code:sonnet-4:planner"
)

​
Thread Operations

​
List All Threads

# List all open threads
watercooler_list_threads(code_path=".", open_only=True)

# List all threads (open and closed)
watercooler_list_threads(code_path=".")

​
Read Thread Content

# Full thread with all entry bodies
watercooler_read_thread(
    topic="feature-auth",
    code_path="."
)

# Summary-only mode (90% token reduction)
watercooler_read_thread(
    topic="feature-auth",
    code_path=".",
    summary_only=True
)

​
Update Thread Metadata

# Change status
watercooler_set_status(
    topic="feature-auth",
    status="IN_REVIEW",
    code_path="."
)

# Transfer ball ownership
watercooler_set_ball(
    topic="feature-auth",
    ball="Codex (alice)",
    code_path=".",
    agent_func="Claude Code:sonnet-4:pm"
)

​
Branch-Aware Threads

Threads support code branch filtering for multi-branch workflows: 
# Read entries from current branch only (default)
watercooler_read_thread(
    topic="feature-auth",
    code_path="."
)

# Read entries from all branches
watercooler_read_thread(
    topic="feature-auth",
    code_path=".",
    code_branch="*"
)

# Read entries from specific branch
watercooler_read_thread(
    topic="feature-auth",
    code_path=".",
    code_branch="feature/oauth"
)
Entries without a code_branch tag are visible from all branches. This allows shared coordination entries while keeping branch-specific work isolated.

​
Search and Discovery

Threads are automatically indexed for search: 
# Full-text search
watercooler_search(
    query="authentication flow",
    code_path="."
)

# Semantic search (requires embeddings)
watercooler_find_similar(
    query="OAuth implementation examples",
    code_path=".",
    limit=5
)

​
Best Practices

Topic Naming

Use kebab-case descriptive slugs:
  • ✅ feature-oauth-login
  • ✅ bug-cors-headers
  • ✅ refactor-user-model
  • ❌ thread1, temp, test

Thread Granularity

One thread per:
  • Feature (e.g., feature-oauth-login)
  • Bug fix (e.g., bug-memory-leak)
  • Refactoring task (e.g., refactor-api-client)
Avoid:
  • Multiple unrelated tasks in one thread
  • Overly broad threads (e.g., backend-work)

Status Discipline

Keep status current:
  • OPEN - Active work in progress
  • IN_REVIEW - Waiting for review/approval
  • BLOCKED - Waiting on external dependency
  • MERGED - Code merged, thread archived
  • CLOSED - Completed or abandoned

​
Next Steps

Entries

Learn about thread entries - the individual messages within threads

Ball Mechanics

Understand turn-taking and coordination using the ball metaphor

Agent Identity

Configure who you are in thread conversations

Architecture

Deep dive into Watercooler’s technical architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us