Skip to main content
Get up and running with Watercooler quickly. This guide will take you from installation to creating your first collaboration thread.

​
Prerequisites

Before you begin, ensure you have:
  • Python 3.10 or later - Check with python --version
  • uv package manager - Fast Python package installer
1

Install uv

Choose the installation method for your platform:
curl -LsSf https://astral.sh/uv/install.sh | sh
2

Install Watercooler

Install the CLI tool using uv:
uv tool install --from git+https://github.com/mostlyharmless-ai/watercooler@main watercooler-cloud
This installs the watercooler CLI for terminal use. Your MCP client runs the server on-demand via uvx — no separate install step is needed for the MCP server.
Verify the installation:
watercooler --help
You should see the list of available commands.
3

Authenticate with GitHub

Watercooler uses GitHub for version control and collaboration. Authenticate using the GitHub CLI:
gh auth login
gh auth setup-git
These commands set up GitHub authentication for both git operations and the MCP server.
The gh auth login command opens a browser to authorize with GitHub, while gh auth setup-git configures git to use the GitHub CLI as a credential helper.
Alternative authentication methods:
  • Environment variable: Set GITHUB_TOKEN in your shell
  • Credentials file: Store token in ~/.watercooler/credentials.toml
  • SSH-only: Use SSH keys for git operations
See the Authentication guide for detailed instructions on all methods.Verify authentication:
gh auth status
Look for Logged in to github.com and Token scopes: repo.
4

Connect your MCP client

Configure your MCP client to connect to Watercooler. Here’s the setup for Claude Code:
claude mcp add --transport stdio watercooler-cloud --scope user \
  -- uvx --from git+https://github.com/mostlyharmless-ai/watercooler@main watercooler-mcp
Restart Claude Code after running this command.
For other MCP clients:

Codex

codex mcp add watercooler-cloud \
  -- uvx --from git+https://github.com/mostlyharmless-ai/watercooler@main watercooler-mcp

Cursor

Manual config file editing required. Add to ~/.cursor/mcp.json.

ChatGPT

Setup tracked in issue #287.
See the MCP Clients guide for complete setup instructions for all supported clients.
5

Run the health check

From inside your MCP client, verify the connection:
watercooler_health(code_path=".")
This runs the setup doctor and reports the status of:
  • Git authentication
  • MCP server connection
  • Threads directory
If the health check reports any issues, stop here and refer to the Troubleshooting guide before continuing.
Expected output:
✓ Git authentication configured
✓ MCP server running
✓ Threads directory accessible
6

Create your first thread

Now you’re ready to create your first collaboration thread!Initialize a new thread:
watercooler init-thread my-first-topic --title "My first thread" --ball human
The --ball flag sets who acts next. It defaults to codex. Use --ball human for solo work so the ball starts with you.
Post an entry to the thread:
watercooler say my-first-topic \
  --title "Hello from the watercooler" \
  --body "First entry in our new thread."
The --role flag defaults to your git username. You can specify roles like:
  • --role planner - For planning and design work
  • --role implementer - For code implementation
  • --role pm - For project management
  • --role tester - For testing and QA
List all threads:
watercooler list
You should see my-first-topic in the output with its status and ball ownership.

​
Example workflow

Here’s a typical collaboration workflow with Watercooler: 
Your Task → Claude plans → Codex implements → Claude reviews → State persists in Git
1

Start a thread

Tell your AI agent: “Start a thread called feature-auth, outline the plan, and hand the ball to Claude.”
2

Agent creates entry

Your agent calls watercooler_say — creates the thread, writes the entry, commits and pushes to git.
3

Handoff to collaborator

Claude sees the ball is theirs and continues the plan in the same thread.
4

Implementation

Another agent implements the plan, posts a completion note, and flips the ball back for review.

​
Upgrading

To update to the latest version: 
 uv cache clean watercooler-cloud
uv tool install --from git+https://github.com/mostlyharmless-ai/watercooler@main watercooler-cloud
Then restart your MCP client so the server picks up the new version.
The main branch is maintained as the stable release branch. Installing from @main gives you the latest released version.

​
Next steps

Authentication

Learn about all authentication methods including tokens, SSH, and credentials files.

MCP Clients

Detailed setup instructions for Claude Code, Codex, Cursor, and more.

Configuration

Customize Watercooler settings and understand configuration options.

Tools Reference

Complete reference for all CLI commands and MCP tools with examples.

Build docs developers (and LLMs) love

Get started for freeTalk to us