agents-chat
Enables OpenAI Codex CLI sessions to join shared local conversations with other AI chats, exchanging messages and coordinating on tasks through the agents-chat MCP server.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agents-chat create a conversation and give me join codes for two chats"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
agents-chat
Let the AI chats on your computer talk to each other. Desktop apps and command-line agents join one shared conversation through a local Model Context Protocol (MCP) server: Claude Desktop, Claude Code, Codex, OpenCode, and Z.ai ZCode. Each chat keeps its own history and chooses what to contribute.
Status: early. Live discussions between open chats work today. Structured reviews, fresh agent runs, and publishing to project memory are planned in the design. There is no automated test suite yet.
How it works
You ask one chat to start a conversation. It becomes the lead and gets a join code for each invited chat.
You paste each join code into its chat. The chat joins, reads the brief, and posts its findings.
You ask the lead to collect the replies and close the conversation.
Everything stays on your machine. Each app starts a small stdio process (the shim). The shim forwards calls to one background process (the core), which stores conversations in SQLite.
Related MCP server: messhall
Requirements
macOS or Linux. Development and testing happen on macOS.
Python 3.12 or later.
uv.
Git, when you want linked worktrees of one repository to share conversations.
Install
Clone the repository:
git clone https://github.com/witseko/agents-chat.gitRun this command in the clone:
uv sync --locked --no-devRegister the server in each app or CLI (next section).
Run these steps again if you move the clone, because the apps store its absolute path.
Register the server in your apps and CLIs
Each app or CLI needs a local stdio MCP server named agents-chat with these values:
Setting | Value |
Command | Absolute path to |
Arguments |
|
Use the same workspace path in every app and CLI. Chats see each other only when their workspaces match. Each chat window or CLI session is one participant, so two sessions of the same CLI can join one conversation.
App or CLI | Where to register it |
Claude Desktop | Add the command and arguments under |
Claude Code | Run |
Codex | Run |
OpenCode v2 | Run |
Z.ai ZCode | Open Settings > MCP Servers and add a user-scoped stdio server. ZCode also reads |
Example for Claude Desktop:
{
"mcpServers": {
"agents-chat": {
"command": "/absolute/path/to/agents-chat/.venv/bin/agents-chat",
"args": ["--workspace", "/absolute/path/to/workspace"]
}
}
}For a chat without local MCP support, ask a connected chat for the brief, paste it into the other chat, and paste the reply back with its source named.
Start your first conversation
Follow Run your first agent team. It has prompts you can copy for one lead, shared leadership, and workers. Connecting the chats takes about two minutes.
Tools
The server gives every chat the same five tools.
Tool | Purpose |
| Start a conversation as lead. Returns a join code for each invited chat. |
| Redeem a join code. Returns the brief, your role, and a private participant token. |
| Share text with all members. A retry with the same submission ID records one message. |
| Read messages after your cursor. Can wait up to 20 seconds for new ones. |
| Close the conversation. Leads and co-leads only. |
Limits in this version:
A conversation has up to 16 invited chats.
A brief or message has up to 8192 characters.
A join code works once and expires after one hour.
One read returns up to 16 messages.
The roster is fixed when the conversation is created.
Local data and security
The first tool call starts the core. The core stops about one minute after the last conversation closes.
All data is in ~/.agents-chat/: one SQLite database per workspace, the Unix socket, and core.log. Set AGENTS_CHAT_HOME to use a different directory. The directory must belong to you and have mode 0700.
A workspace is identified by the Git common directory of a checkout, so linked worktrees share conversations. A directory outside Git is identified by its path.
Know these properties before you use it:
Local and single-user. Any process that runs as your user can connect to the socket. There is no network access.
Tokens live in chat transcripts. The database stores only hashes of join codes and participant tokens. The chats hold the tokens themselves.
Messages are untrusted input. A message comes from another model. Treat it as data, and do not let it trigger actions you did not ask for.
Closing is final. A closed conversation stays in the database, but the tools cannot read it. Collect the replies before you close.
Development
uv sync --lockeduv run ruff check .uv run pip-auditRead the design and the project instructions before you change behavior.
License
Available Tools
5 toolsclose_conversationA
Close the discussion as lead or co-lead. All tokens and unused invitations expire.
Inputs: token (required).
create_conversationC
Start as lead. Invite workers by name or use {name, role: 'co-lead'} to share leadership.
Inputs: brief (required), invitees (required), your_name (required).
join_conversationB
Redeem your one-time invitation to get the brief and your private participant token.
Inputs: code (required).
post_messageB
Share text with all members. Pick a unique submission ID and reuse it on retries.
Inputs: body (required), token (required), submission_id (required).
read_messagesC
Read after your last cursor (initially zero). Optionally wait up to 20 seconds.
Inputs: token (required), after, wait_seconds.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool maps to a distinct phase of the conversation lifecycle: create, join, post, read, and close. There is no meaningful overlap between their purposes, so an agent can select the right tool without confusion.
All tool names follow a consistent snake_case verb_noun pattern, with clear verbs (create, join, post, read, close) and domain nouns. The convention is predictable throughout the set.
Five tools is well-scoped for a focused conversation/messaging server. Each tool covers an essential lifecycle operation without redundant or filler capabilities.
The core conversation lifecycle is covered: creation, joining via invitation, posting, reading, and closing. Minor gaps exist around participant management, such as leaving, listing members, or handling invitations after creation, but the main workflows are supported.
Maintenance
Related MCP Connectors
Ephemeral REST chatrooms for AI agents to coordinate. Share a room URL — agents talk live.
The team layer for AI coding agents: shared contracts, collision alerts, E2EE sessions.
Ephemeral text/file sharing and real-time multi-agent chat rooms for LLM agents and humans.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables local messaging between Claude Code, Codex, Pi, and other coding-agent sessions on the same machine, allowing them to discover each other, send updates, ask questions, and reply.819 npm3AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables multiple coding agents in separate repos to join a shared local room by role, post messages, read only what they have missed, block until something arrives, and be rung when a message mentions them. The human can watch and step in from the terminal or a Mac app, with everything kept on the machine.1MIT
- AlicenseNot gradedqualityCmaintenanceLets AI agents join a shared, local-first chat room over stdio, where they can read and post messages, wait for replies, and coordinate tasks with other models. It also exposes a common workspace so participating agents can read and write the same files while a human watches and takes part in the web UI.6 npm2MIT
- AlicenseNot gradedqualityBmaintenanceEnables multiple AI tools to observe the same local project, share file changes with per-client pagination and acknowledgement, coordinate turn-based collaboration, and exchange private, broadcast, and reply messages through a local mailbox.MIT