agentchattr: a chat server that pokes your terminals

The transport is a write to a terminal

Everything else about this project follows from one decision, so it is worth being explicit.

The server does not call an agent API. Nobody built a client for Claude Code or Codex. When you type a mention in the chat, the server writes text into that agent's terminal, the agent reads the conversation because it is already a participant in it, and it responds. The README's own description of the loop says the server detects the mention, the wrapper injects a prompt about being mentioned into the agent's terminal, and the agent then reads recent messages and answers in the channel.

That has a long tail of consequences, and most of the repository's structure is that tail. The wrapper exists because writing to a terminal is platform-specific, and the tree has three files for it: a shared wrapper module plus one for Unix and one for Windows. An MCP bridge and an MCP proxy exist because the agents need a structured way to read and send messages once they are awake, rather than parsing the chat. The tmux dependency exists because an agent running inside a plain terminal window dies when the window closes, whereas an agent inside a named session can be detached and reattached. The manual escape hatch, typing a read command for the default channel into the agent's terminal, exists because sometimes the injection will not fire and you need to poke it yourself.

The upside is real: no adapter per agent, and therefore a new MCP-compatible client works without a code change. The downside is equally real: the agent must already be running in a terminal the server can reach. Every launcher in the repository exists to arrange that.

A loop guard, per channel, that you cannot override

Two agents that can mention each other will, given time, mention each other for ever. The design answer here is a loop guard, and its details matter more than the existence of it.

The guard is per channel. When a conversation in one channel reaches a configured number of hops, that channel's agent-to-agent chain pauses and waits for a human. Other channels are unaffected, so a runaway conversation in the debugging channel does not silence the general channel you were watching. A global guard would have been simpler to implement and wrong in a way that matters, because the failure it introduces is silence rather than noise.

The second detail is better. Human mentions always pass through, even when the guard is active. So the guard cannot lock you out of a channel it has paused; you can always get a response from a specific agent by naming it, and you resume the chain deliberately. The README describes that as typing a continue command.

So the safety model is not a sandbox. It is a brake that a human can always override and that degrades one channel at a time rather than all of them. That is the right shape for a tool whose whole purpose is removing you from the loop, and it is worth understanding precisely because there is nothing else holding it back.

The README does not say what the hop count is or how it is configured, which is the first thing to look for in the configuration when you install this, because that number is the entire tolerance you have given the agents.

The auto-approve launchers are the real risk surface

Each agent has two launchers, and the second one is named after what it does to the permission model.

The repository ships variants that start the agents with their approval prompts disabled: a Claude launcher passing a flag that skips permissions, a Codex launcher passing a flag that bypasses approvals and the sandbox, and Gemini and Qwen launchers passing their equivalent flag. The README labels the group in one line: agents run tools without asking permission.

That is not an accident of the packaging, it is a consequence of the design. An approval prompt needs a human who is reading the terminal. This product's entire premise is that agents wake each other up while you are doing something else, so at the moment a tool call is proposed there may be nobody there to approve it, and the prompt will sit unanswered until the agent's turn has already timed out. A tool for multi-agent coordination needs unattended agents.

Which means the choice is real rather than cosmetic. The normal launchers give you an approval prompt that mostly nobody reads, which trains you to reflexively approve. The auto-approve launchers remove the fiction and are honest about it, and they hand every agent the ability to run commands without a checkpoint.

The practical position is that these are separate launcher files rather than a flag you discover later, which is a good design choice, and that the safer path is to launch with the normal variants and treat a stalled approval prompt as information rather than noise. If you do use the auto-approve variants, do it in a repository where nothing irreversible is one command away, because the coordination you gain is being able to walk away from the screen.

Two platforms, two launcher conventions, one tmux requirement

Installation is deliberately different on Windows and everywhere else, and the difference is not cosmetic.

On Windows you open a folder and double-click a batch file. There is a launcher per agent, plus one that starts only the chat server. On first launch the script creates a virtual environment, installs the Python dependencies and configures the MCP connection, so the setup is a double-click rather than a sequence of commands. Each agent launcher also starts the chat server if one is not already running, which means you can launch agents in any order and they will find each other.

On Mac and Linux the same list exists as shell scripts, and the README asks for one thing first:

brew install tmux    # macOS
# apt install tmux   # Ubuntu/Debian

That is because the agent is launched inside a tmux session rather than a bare terminal, which is what makes the injection mechanism survivable. The agent keeps running after you detach, and you reattach with a named session:

tmux attach -t agentchattr-claude

The naming convention is per agent, so a machine running four agents has four sessions you can reattach to individually and read what each one is doing. On Windows the equivalent guarantee comes from the launcher starting the server in a separate window, and from the fact that the release history contains a fix for terminal rendering on Windows, which is the kind of platform detail that only shows up once you have actually run it there.

The chat itself is the same on both: a browser page on a local port, with an HTML file you can open directly if you would rather not use the address. Agents are addressed by a short mention handle, and there are toggle buttons above the input for people who would rather click.

Three dependencies and one pinned comment

The requirements file is three lines, and one of them explains itself:

fastapi>=0.110
uvicorn[standard]>=0.29
mcp>=1.0,<2.0  # v2 removes mcp.server.fastmcp (issue #85)

That is the whole server. A web framework, an ASGI server, and the Python SDK for the protocol agents use to talk to tools. There is no database driver, no message queue, no front-end framework and no container orchestration, because the chat state is local and the interface is a single page.

The pin is worth noticing as a piece of engineering hygiene. An upper bound on a dependency, with a comment saying what breaking change it is guarding against and an issue number to read about it. That is what an upper bound is for, and it is a better artefact than either an unbounded range or a bare version with no explanation.

It also tells you something about the fragility. If the protocol SDK can remove a module in a major version, then this project's ability to run at all depends on a dependency outside its control that has a stated breaking change pending. The comment means somebody hit it and wrote it down. If you are deploying this, that is the line to watch in a dependency audit.

The rest of the surface area is small too. The repository has no build step for the web page, since the interface is served as static files from a folder, and the release process has a script and a version file rather than a packaging pipeline.

A third of the modules are not in the README

The documented feature set is chat, channels, mentions and the loop guard, and that part of the README is thorough. The file list tells a larger story.

There is a session engine, a session store and a directory of session templates, which together suggest persistent agent sessions rather than transient terminal processes. There is an archive module and a store module, which together suggest history is kept rather than discarded with the terminal. There are modules for schedules, jobs, summaries and rules, which is the vocabulary of a system that runs things on a timer and keeps notes about what happened.

There are also two separate MCP modules, a bridge and a proxy, and a router and a registry, and configuration in a TOML file with a separate example file for local overrides. And there are three wrapper modules for what the README describes as one mechanism.

None of that is criticism. A project that starts as a proof of concept and gets a chat interface working often accumulates infrastructure that the README has not caught up with, and the README in this case is clearly written for a person evaluating the tool rather than for a person auditing it. But the practical consequence is real: if you are choosing this because you want persistent agent sessions or scheduled jobs, the evidence for that is in the file list rather than in the documentation, and you should go and read those modules before you install on the strength of the chat.

For the feature the README does cover, everything relevant is in the first half. Channels behave like channels, the default is called general, they persist across server restarts, and you can create, rename and delete them from the channel bar.

What this is not for

Three cases.

If you run one agent, this solves nothing. The whole premise is several agents and a human who does not want to be the switchboard, and a single agent with one terminal is simpler and has one fewer thing that can deadlock.

If you need a shared, multi-user agent chat, this is not it. The server is described as local, the interface is on a local port, and the README says nothing about authentication or authorisation. Treat that port as open to anything that can reach it and do not bind it to an interface you do not control, because anything that can post into a channel can wake an agent, and a woken agent runs tools with whatever permissions its launcher granted. That chain from an unauthenticated HTTP request to a shell command is the security property to reason about, and the loop guard does nothing for it.

If you need an audit trail of who told an agent to do what, the history here is a chat log in a local store, and the design is optimised for a conversation rather than for a record. Agents can mention each other, so attributing an action to the agent that took it rather than the agent that triggered it is your problem.

What it is for is narrow and stated plainly in the project description: a free local chat where coding agents can tag each other, talk and coordinate with you. For a single developer running several agents at once, that is a real gap, and this fills it in about three dependencies and a tmux install.

Editorial conclusion

Adopt agentchattr if you run several coding agents and want one to hand work to another without you relaying messages, and start with the launchers that do not skip permission prompts, because the design removes you from the loop and the approval prompt is the only place left where you were in it. Read the loop guard's behaviour before you enable cross-agent mentions: it pauses per channel after a set number of hops and a human mention always passes through, and that override is the safety property that matters. Do not expose port 8300 beyond your own machine, and check what the undocumented session, archive and schedule modules are doing before assuming this is only a chat.

Frequently asked questions

Official sources

1. bcurts/agentchattr on GitHub
2. Issues
3. License: MIT
4. README
5. Releases