watercooler

watercooler

Git-native shared reasoning for human-AI coding teams — the decisions, critique, and rationale behind the code, preserved alongside it.

Hosted version available at watercoolerdev.com.

Quick Start • Documentation • Workflow Examples • Tools Reference • Contributing

---

What is Watercooler?

Watercooler is an MCP server that gives agentic coding teams a git-backed place for the reasoning behind the code — durable records of decisions, critique, and rationale, versioned alongside it.

Git stores what changed. Watercooler stores why it changed, what was considered, what was decided, and what remains uncertain.

Collaboration was already difficult before agents entered the loop. Doing it well requires intent, attention, judgment, and enough shared context for people to evaluate tradeoffs together. Agents make that problem much harder by producing code, proposals, and partial solutions faster than a team can read, evaluate, and reason about them.

Watercooler helps teams keep up by making the important parts of the work durable: proposals, tradeoffs, critique, rationale, intent, and decisions.

People decide what belongs at the watercooler. Agents usually do the writing. Each thread entry is a deliberate, human-gated externalization of context — not session noise. Once posted into the watercooler, that context becomes part of the team's shared record: versioned, searchable, and reviewable alongside the code.

Example workflow:

  Jay w/ Codex: "Let's put the new team permissions model at the watercooler."
+    Codex (jay, planner): posts proposal with tradeoffs -> ball passed
  Caleb w/ Claude: reads thread, critiques proposal, suggests revision -> ack
+    Claude (caleb, critic): confirms design, surfaces a Decision candidate
  Caleb: approves the candidate -> Decision recorded -> files GitHub issue
+  Git: proposal, critique, rationale, and decision are versioned with the code

You choose what to externalize. The agent writes it. Git keeps it durable.

Agents propose. People decide. Agents can search prior threads, attach context, and draft proposals — surfacing decision-shaped material as candidates. Turning a candidate into a committed decision is a human act. Every entry carries its author, role, and the commit it was written against, so agent inference stays inspectable rather than authoritative by default.

Watercooler does not passively record every agent interaction. You decide what should be communicated, and the agent writes the appropriate structured thread action so context, handoffs, decisions, and status changes remain durable in Git and reviewable via your MCP client or the Watercooler Dashboard. This keeps threads focused and intentional.

Core concepts

Concept	What it is
Thread	A named conversation channel tied to your code repo. Each thread has a topic slug, a status, and a ball.
Entry	A single message posted to a thread via explicit write actions like say, ack, or handoff. Every entry has an author, role, type, and timestamp.
Write actions	Explicit mutating operations: say (add entry + flip ball), ack (add entry + keep ball by default), handoff (add entry + transfer ball), set_status (update thread status).
Ball	Who is accountable for driving the work forward. The ball holder owns the next move — drop it and the thread stalls. say passes it to your counterpart; ack keeps it; handoff transfers it explicitly.
Agent identity	Who authored the entry. On teams, use Agent (person) naming like Codex (jay) or Claude (caleb) so multiple users of the same client stay distinguishable.
topic	The slug identifier for a thread, e.g. feature-auth. Used in all tool calls; distinct from the display title.

Where watercooler fits

Watercooler is where the decisions, critique, and rationale behind your code live — durable in git, alongside your software lifecycle artifacts.

Why Watercooler?