agents-room
Coordination for AI coding agents that work in different repositories and
have to agree with each other.
Landing page → ·
Русская версия →
Try it in 60 seconds
GOBIN=~/.local/bin go install github.com/asovetov/agents-room/cmd/agents-room@latest
agents-room doctor --fix # wires the MCP server and the hooks into what it finds
Then, from two checkouts of the same product:
cd ~/src/api && agents-room join --also shared:storefront --label "users API"
cd ~/src/mobile && agents-room join --also shared:storefront --label "mobile app"
agents-room who --room shared:storefront
The problem
A team keeps three repositories: api (a REST service), web (the storefront
that calls it) and mobile (the app). Each has its own agent sessions, in
its own terminal, often with its own harness.
The mobile agent needs a field the API does not return yet. The API agent is
midway through renaming something else. The web agent is building against the
current shape and will break if the rename lands without them knowing.
Nothing in any harness connects those three windows. So you become the
courier: you copy the request from one chat into another, you remember who
promised what, and you find out about the break when the build fails.
agents-room is the layer that is missing. It lets agents in different
repositories meet in a room, say what they need from each other, and hold
the files they are working on while the agreement is being made.
It answers three questions the harnesses do not:
- Who is working on this interface? Which sessions are in the room, in
which repository, and which of them are actually still running.
- Who is touching this file? Leases on paths, with expiry and
stale-holder detection — across repositories, not just within one.
- Is my read still valid? A warning when a file changed under you.
It also delivers messages addressed by what rather than who:
file:src/api/users.go reaches whoever holds that file in your repository,
and file:api:src/api/users.go reaches the holder in another one, with the
path written as it appears there; tag:mobile reaches everyone working on
the mobile client.
The same works inside one repository, when several sessions share a codebase.
That is the simpler case, and it comes for free.
A session, in thirty seconds
# In the api repository: join the room the three projects share.
agents-room join --also shared:storefront --label "users API" --tag backend
# The api agent claims the file before editing, so the others can see it.
agents-room lease claim --session $ID --path src/api/users.go
# In the mobile repository: ask whoever holds the users endpoint.
# file:<repo>:<path> reads the path from that repository's checkout.
agents-room send --session $ID --to file:api:src/api/users.go \
--subject "need a phone field" --body "for the profile screen"
That is the whole loop. Everything else — MCP tools, harness hooks, autonomy
levels — is about making it happen without you typing.
How the repositories meet
Every session joins repo:<name of its directory> automatically. Those rooms
stay separate: agents in api do not see web's work unless they are asked
to.
To work across repositories, sessions join a shared room — a named group
that any repository can enter:
agents-room join --also shared:storefront
A shared room is not a merge of the repository rooms. It is a meeting point:
api, web and mobile each keep their own room, and the agents that opted
in can reach each other in the shared one. Leases, messages and tags all work
there, so an agent in mobile can hold a file in api while it asks for the
change.
The hook discovers shared rooms from two optional sources, so nobody has to
remember a flag:
# once, in your shell profile: every repository on this machine
export AGENTS_ROOM_SHARED=storefront
# <repository>/.agents-room/shared-rooms: travels with the checkout
storefront
A join run from the CLI or an MCP tool does not read those sources — pass
--also storefront or extra_rooms yourself there. The shared: prefix is
added when missing, so storefront and shared:storefront are one room, not
two that look alike.
Why not just use the harness
Most harnesses can message another session if you know its id. They do not
know which sessions are working on the interface you are about to change,
which files are contested, or whether the agent that was editing a file is
still alive. That is the gap this fills.
| Harness messaging | agents-room |
|---|
| Reach a session by id | yes | yes |
| Reach whoever holds a file, in any repository | no | yes, file: selector |
| Reach everyone on a topic, across repositories | no | yes, tag: selector |
| Know who is in the room | no | yes, who |
| Know if a chat is still running | no | yes, alive / gone |
| Stop two agents editing one file | no | yes, leases |
| Warn that a file moved under you | no | yes, drift |
| Meet agents from other repositories | no | yes, shared rooms |
This is the beginning of the README. Read the rest at the original. Read the full README ↗
