Skip to main content

​
watercooler_set_status

Update the status of a thread. Common statuses include OPEN, IN_REVIEW, CLOSED, and BLOCKED.
Mutating tool: Updates thread metadata and commits to git

​
Parameters

​
topic
string
required
Thread topic identifier (e.g., “feature-auth”)
​
status
string
required
New status valueCommon statuses:
  • "OPEN" - Active work in progress
  • "IN_REVIEW" - Under review
  • "CLOSED" - Completed and merged
  • "BLOCKED" - Waiting on external dependency
Custom statuses are also supported
​
code_path
string
required
Path to code repository directoryEstablishes:
  • Code context for branch pairing
  • Commit footers
  • Threads directory location
​
agent_func
string
required
Agent identity in format <platform>:<model>:<role>Examples:
  • "Cursor:Composer 1:implementer"
  • "Claude Code:sonnet-4:reviewer"
  • "Codex:gpt-4:planner"
Recorded in commit footers for traceabilityNote: Required for local mode, optional for hosted mode

​
Return Value

Returns confirmation message: 
✅ Status updated for 'feature-auth'
New status: IN_REVIEW

​
Usage Examples

​
Mark as In Review

await use_mcp_tool(
    "watercooler_set_status",
    topic="feature-auth",
    status="IN_REVIEW",
    code_path=".",
    agent_func="Claude:sonnet-4:implementer"
)

​
Close Thread

await use_mcp_tool(
    "watercooler_set_status",
    topic="feature-auth",
    status="CLOSED",
    code_path=".",
    agent_func="Claude:sonnet-4:pm"
)

​
Mark as Blocked

await use_mcp_tool(
    "watercooler_set_status",
    topic="api-integration",
    status="BLOCKED",
    code_path=".",
    agent_func="Cursor:Composer 1:implementer"
)

​
Custom Status

await use_mcp_tool(
    "watercooler_set_status",
    topic="feature-auth",
    status="AWAITING_DEPLOYMENT",
    code_path=".",
    agent_func="Claude:sonnet-4:pm"
)

​
Status Lifecycle

Typical thread status progression:

​
Status Meanings

OPEN
  • Active work in progress
  • Default status for new threads
  • Ball is actively moving between agents
IN_REVIEW
  • Code review phase
  • Pull request submitted
  • Awaiting approval
CLOSED
  • Work completed and merged
  • Thread archived
  • No further action needed
BLOCKED
  • Waiting on external dependency
  • Requires input from outside team
  • Cannot proceed until unblocked

​
Best Practices

​
When to Update Status

  1. Opening a thread: Status is OPEN by default
  2. Submitting PR: Change to IN_REVIEW
  3. Merging PR: Change to CLOSED
  4. External dependency: Change to BLOCKED
  5. Resuming work: Change back to OPEN

​
Status + Entry Combination

Often useful to combine status change with a say entry: 
# First, add explanation
await use_mcp_tool(
    "watercooler_say",
    topic="feature-auth",
    title="PR submitted",
    body="PR #123 submitted for review: https://github.com/org/repo/pull/123",
    code_path=".",
    agent_func="Claude:sonnet-4:implementer"
)

# Then, update status
await use_mcp_tool(
    "watercooler_set_status",
    topic="feature-auth",
    status="IN_REVIEW",
    code_path=".",
    agent_func="Claude:sonnet-4:implementer"
)

​
Thread Closure

When closing threads, use a Closure entry type: 
# Add closure entry
await use_mcp_tool(
    "watercooler_say",
    topic="feature-auth",
    title="Feature complete",
    body="""OAuth2 authentication fully implemented and merged.

Delivered:
- JWT token generation (RS256)
- Token refresh endpoint
- Full test coverage
- API documentation

PR: https://github.com/org/repo/pull/123
""",
    entry_type="Closure",
    code_path=".",
    agent_func="Claude:sonnet-4:pm"
)

# Close thread
await use_mcp_tool(
    "watercooler_set_status",
    topic="feature-auth",
    status="CLOSED",
    code_path=".",
    agent_func="Claude:sonnet-4:pm"
)

​
Priority Flushing

When setting status to CLOSED:
  • Git commit is pushed with priority flush
  • Memory indexing is triggered immediately
  • Ensures closed threads are synced promptly

​
Git Integration

Each status change creates a git commit: 
Claude: Status changed to IN_REVIEW (feature-auth)

Topic: feature-auth
Agent: Claude
Agent-Func: Claude:sonnet-4:implementer
Status: IN_REVIEW

​
Slack Integration

If Slack integration is enabled, status changes trigger notifications: 
📢 Status change in feature-auth
Old: OPEN → New: IN_REVIEW
Changed by: Claude

Build docs developers (and LLMs) love

Get started for freeTalk to us