teamroom

Run agents in parallel.
Know when their work overlaps.

teamroom shares file activity and plans across Claude Code, Codex, Cursor, Gemini CLI, and your teammates—even before changes are committed or pushed.

Local by default. No server required.

Two worktrees. One shared file to think about.

Codex is updating the theme. Claude Code is changing the header. Both need src/theme.ts. Worktrees keep their edits separate; teamroom surfaces the overlap.

Worktree 1 Codex, feat/theme
The room .git/teamroom, this machine
Worktree 2 Claude Code, feat/header

Illustrative walkthrough · five stepsTheir files are isolated. Their tasks still overlap. Step through how a warning can help them adjust.

This example shows a possible response to a warning, not a guarantee of a clean merge. Claude Code and Gemini CLI hooks pause overlapping edits once. Other teamroom integrations rely on MCP checks; background warnings arrive on the next teamroom tool call.

Worktrees isolate the edits.
teamroom shares the context.

Claude Code, Cursor, and Codex already offer native worktree workflows. Git worktrees work with any coding tool. Add teamroom when independent sessions need to know who else is changing the same files.

What worktree isolation provides, and what a connected teamroom adds
CapabilityWorktrees aloneWith teamroom
Separate files for parallel agentsYesProvided by your worktrees
Shared view of uncommitted and untracked file activityNot provided by isolationAutomatic reports
Plans visible before code existsNot provided by isolationNotes with expected file paths
File overlap warnings across independent toolsNot provided by isolationHooks and MCP checks
Teammates’ file activity before they pushNot provided by isolationOptional shared server
Understand whether changes actually conflictGit detects textual conflicts at mergeFile overlap only; no merge simulation or semantic analysis

Native platforms also offer coordination: Claude Code agent teams share tasks and messages, and Cursor Projects coordinate their agents. This table compares worktree isolation. teamroom adds awareness across independent tools and teammates. Sources checked September 28, 2026.

One agent, or clearly separate tasks? Worktrees may be enough. Use teamroom when overlapping work is hard to see until integration. Warnings are advisory: same-file edits can be compatible, and different-file changes can still conflict.

How the room stays informed

Git hooks and background reports share actual changes. Agents can add plans and ask about files before editing. Warning delivery depends on the integration.

Git hooks

Reports after Git events.

  • Fires after every commit, checkout, merge and rebase.
  • Shares every file this checkout has changed compared with main, including uncommitted and untracked ones.
  • Runs in the background. Nothing it does can fail a commit.

MCP server

Any agent, all session long.

  • Shares the checkout's changes every few seconds while the agent works, without being asked.
  • When another session starts changing the same file, the next teamroom tool result opens with a heads-up.
  • teamroom_post_note announces a plan, teamroom_check_overlap asks before editing.

Agent hooks

Pauses an edit once in Claude Code and Gemini CLI.

  • A new session is briefed on what the other sessions are changing.
  • An edit to a file someone else is in is paused once, with who and why. The retry goes through.
  • Every edit is shared the moment it happens.

Reports share what changed. Warnings give agents a chance to adjust.

Where everything lives

By default the room is a file in your repo's .git directory, which every worktree shares. No server, no account, nothing leaves your machine. To include teammates on other machines, point the repo at a small shared server instead.

Worktree 1 reports its changes through git hooks and its agent's MCP server to a room file in .git. The agent in worktree 2 checks the same file before editing. Worktree 1 Codex, feat/theme post-commit hook teamroom mcp AGENTS.md The room sessions, files, plans .git/teamroom/ or a shared server Worktree 2 Claude Code, feat/header pre-edit hook teamroom mcp session briefing report check overlap
Automatic: hooks and background reports On request: tools the agent calls

What the room sees

Three kinds of entries. Each one carries a session, a branch, the agent that sent it, and a list of file paths.

wip

Work in progress

Every file a checkout has changed but not merged yet. A new snapshot from the same checkout replaces the old one, so finished work stops showing up.

edit

Agent edits

A file an agent just edited, sent by its hook the moment it happens. The session's next snapshot replaces it, so reverted edits stop counting.

note

Plans

What an agent or a person is about to do, like "renaming User to Account", with the files it expects to touch. Hooks and overlap checks can surface the plan before another agent edits them.

File contents are never shared. In local mode nothing leaves your machine at all. A shared server gets paths, branch names, commit ids and short messages; tokens are stored hashed there and kept in .git/teamroom.json on yours, readable only by you. Lockfiles are left out of overlap, and .teamroomignore leaves out more.

Get started

You need Node 22 or newer and git. No server, no account.

  1. Install

    npm install --global teamroom

    Hooks and agent configs launch teamroom by name, so it needs to be on your PATH.

  2. Set up your repo, once

    teamroom init

    Adds git hooks, MCP config for the agents it finds, an AGENTS.md block and hooks for the agents that support them. Commit what it wrote.

  3. Give each agent its own worktree

    git worktree add ../app-header -b feat/header
    cd ../app-header && codex   # or claude, gemini, vibe

    Each worktree is its own session. Worktrees you add later are set up automatically.

  4. Watch them work

    teamroom watch                # every session, live
    teamroom check src/theme.ts   # who else is in this file

    Use the dashboard or check a file yourself. Agents receive warnings through the hooks and MCP checks described above.

  5. Optional: bring in teammates

    teamroom create --server https://teamroom.example.com
    teamroom join '<invite link>'   # on their machines

    Needs a server your team can reach: teamroom serve, or the Docker image on Fly.io.