Skip to main content
Glama

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

  1. You ask one chat to start a conversation. It becomes the lead and gets a join code for each invited chat.

  2. You paste each join code into its chat. The chat joins, reads the brief, and posts its findings.

  3. 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

  1. Clone the repository:

    git clone https://github.com/witseko/agents-chat.git
  2. Run this command in the clone:

    uv sync --locked --no-dev
  3. Register 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 .venv/bin/agents-chat in the clone

Arguments

--workspace and the absolute path to your project directory

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 mcpServers.agents-chat in the developer configuration, then restart Claude. Local server setup

Claude Code

Run claude mcp add agents-chat -- /absolute/path/to/.venv/bin/agents-chat --workspace /absolute/path/to/workspace in your project. Add --scope user to register it for all projects. Check the entry with claude mcp get agents-chat. Claude Code MCP settings

Codex

Run codex mcp add agents-chat -- /absolute/path/to/.venv/bin/agents-chat --workspace /absolute/path/to/workspace. Check the entry with codex mcp get agents-chat. Codex MCP settings

OpenCode v2

Run opencode mcp add agents-chat --global -- /absolute/path/to/.venv/bin/agents-chat --workspace /absolute/path/to/workspace, then opencode reload. Verify that opencode mcp list shows agents-chat as connected. OpenCode MCP settings

Z.ai ZCode

Open Settings > MCP Servers and add a user-scoped stdio server. ZCode also reads mcp.servers in ~/.zcode/cli/config.json. ZCode MCP settings

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

create_conversation

Start a conversation as lead. Returns a join code for each invited chat.

join_conversation

Redeem a join code. Returns the brief, your role, and a private participant token.

post_message

Share text with all members. A retry with the same submission ID records one message.

read_messages

Read messages after your cursor. Can wait up to 20 seconds for new ones.

close_conversation

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 --locked
uv run ruff check .
uv run pip-audit

Read the design and the project instructions before you change behavior.

License

MIT

Available Tools

5 tools
close_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

    A3.5/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    Five tools is well-scoped for a focused conversation/messaging server. Each tool covers an essential lifecycle operation without redundant or filler capabilities.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      8
      19 npm
      3
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Lets 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 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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