watercooler_handoff
Hand off the ball to another agent. If target_agent is specified, hands off to that agent. If omitted, hands off to your default counterpart.
Mutating tool: Updates ball owner and commits to git
Parameters
Thread topic identifier (e.g., “feature-auth”)
Optional handoff message explaining context
Agent name to receive the ballIf null, hands off to your configured counterpart
Path to code repository directoryEstablishes:
- Code context for branch pairing
- Commit footers
- Threads directory location
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 and entry metadata Return Value
Returns confirmation message:
✅ Ball handed off to: Cursor
Thread: feature-auth
Status: OPEN
Note: Ready for your review
Usage Examples
Handoff to Counterpart
await use_mcp_tool(
"watercooler_handoff",
topic="feature-auth",
note="Ready for your review",
code_path=".",
agent_func="Claude:sonnet-4:implementer"
)
Handoff to Specific Agent
await use_mcp_tool(
"watercooler_handoff",
topic="feature-auth",
target_agent="Cursor",
note="Can you test this on your setup?",
code_path=".",
agent_func="Claude:sonnet-4:implementer"
)
Silent Handoff (No Message)
await use_mcp_tool(
"watercooler_handoff",
topic="feature-auth",
target_agent="Cursor",
code_path=".",
agent_func="Claude:sonnet-4:implementer"
)
Multi-Agent Handoff
# Hand off to specific agent in 3+ agent workflow
await use_mcp_tool(
"watercooler_handoff",
topic="complex-refactor",
target_agent="Reviewer-Agent",
note="""Code review needed:
- Check error handling in src/auth/jwt.py
- Verify test coverage
- Review API documentation
""",
code_path=".",
agent_func="Claude:sonnet-4:implementer"
)
When to Use
Use handoff when:
- Explicit transfer: You want to explicitly pass responsibility
- Multi-agent workflows: You need to route to a specific agent
- Blocking issues: You’re blocked and need someone else to proceed
- Task completion: You’ve finished your part and want to hand off
Use say for normal back-and-forth collaboration (ball flips automatically).
Ball Mechanics
Default Counterpart
If target_agent is null:
- Claude hands off to Cursor
- Cursor hands off to Claude
- Custom counterparts via
WATERCOOLER_COUNTERPART
Explicit Target
If target_agent is specified:
- Ball goes to exactly that agent
- Useful for 3+ agent workflows
- Useful for routing to specialists
Handoff Patterns
Implementer → Reviewer
# After implementing feature
await use_mcp_tool(
"watercooler_handoff",
topic="feature-auth",
target_agent="Reviewer",
note="Implementation complete, ready for code review",
code_path=".",
agent_func="Cursor:Composer 1:implementer"
)
Reviewer → Implementer
# After review
await use_mcp_tool(
"watercooler_handoff",
topic="feature-auth",
target_agent="Cursor",
note="Review complete. Found 2 issues - see comments above",
code_path=".",
agent_func="Claude:sonnet-4:reviewer"
)
Planner → Implementer
# After planning
await use_mcp_tool(
"watercooler_handoff",
topic="refactor-api",
target_agent="Cursor",
note="Plan approved. Ready for implementation",
code_path=".",
agent_func="Claude:sonnet-4:planner"
)
Git Integration
Handoff with note creates a git commit:
Claude: Handoff to Cursor (feature-auth)
Entry-ID: 01ARZ3NDEKTSV4RRFFQ69G5FAV
Topic: feature-auth
Agent: Claude
Agent-Func: Claude:sonnet-4:implementer
Ball: Cursor
Slack Integration
If Slack integration is enabled, handoffs trigger notifications:
🎾 Ball handoff in feature-auth
From: Claude → To: Cursor
Note: Ready for your review
