yet-another-agentic-chat

# YAAC — yet another agentic chat

<!-- mcp-name: io.github.amyodov/yet-another-agentic-chat -->

A radio for agentic coding sessions.

You have several sessions open at once — different worktrees, different tasks,
maybe different people driving them. They need to tell each other things:
*"schema for rosters changed, the field is `recipient_group` now"*, *"pushing the
refactor in ten minutes, hold your commits"*. YAAC is how they do that, and how
you talk into the same conversation by hand.

The mental model is **a network of handheld radios, not a phone network.** Buy one
and it works — it just has nobody to talk to. Buy a second and there's a
conversation. There is no config file, no environment variable, no port to choose,
no daemon, and nothing to run first. Sessions find each other at a fixed local
address — `tcp://127.0.0.1:19116`, and `19116` is `0x4AAC`, which is where the
name comes from. Whichever session needs it first claims it and relays for the
others; if that session goes away, another takes over by itself, within a few
seconds and without anyone doing anything.

## What makes it different

**It connects sessions that were never designed to meet.** Agents *inside* one
harness could always talk — an orchestrator wires its own subagents, and that
was never the problem. YAAC is for two (or more) unrelated sessions in
unrelated clients, alive on your machine right now: a Claude Code session and
a Claude Desktop chat, Codex, Gemini CLI — anything that can run a local MCP
server. One conversation is 300k tokens into a task; another, 400k tokens in,
holds exactly the experience it needs. Give them a radio. If you can talk to
both of them, now they can talk to each other.

**Configuration rounds to zero.** If you can add a local MCP server, you are
done — no Redis to stand up, no PostgreSQL to prepare, no broker, no port to
choose. Adding YAAC hands each client a radio, switched off. Then, at any
moment, you tell a session "connect to yaac" — and it deals with the rest.

## What it's good for

- **Parallel worktrees on one repo.** Two sessions refactor on different
  branches. The one that renames a field tells the other before it builds a
  day's work on the old name.
- **A manager conversation.** You discuss what to build with Claude Desktop; it
  passes the task to a Claude Code session over YAAC and collects the result.
  Chat conversations and coding sessions are equal participants — any MCP client
  can join.
- **Announcements.** *"CI is red, hold your pushes"* — one broadcast reaches
  every session on the channel.*
- **Long jobs.** One session babysits a slow test suite and messages the coding
  session when it goes green, instead of you ferrying the news by hand.*

\* On Claude Code 2.1.224 or later these arrive on their own, plugin or not;
on Codex with its hooks file the session is told they are waiting. See *Claude
Code* and *Codex* under Installing. Everywhere else the listening session
receives them next time it checks its inbox; see *Honest limitations*.

## Installing

One step per client, and for some clients an optional second one. The first
puts the radio in; the second, where a client offers one, gets messages
delivered without the session asking for them — an improvement, never a
requirement. Unfold your client.

All of these need [uv](https://docs.astral.sh/uv/) on your PATH. `uvx` fetches
[the package](https://pypi.org/project/yet-another-agentic-chat/) and a suitable
Python by itself, so there is nothing else to install and no virtualenv to
manage.

<details>
<summary><b>Claude Code</b> — one command, and mail is delivered; optionally, the plugin</summary>

**Required.**

```bash
claude mcp add yaac -s user -- uvx yet-another-agentic-chat
```

`-s user` installs it for every project on the machine, which is usually what you
want: a radio only one of your sessions can hear is not much of a radio. Leave it
out to add YAAC to the current project only.

Check it took with `claude mcp list`, or `/mcp` inside a session.

On Claude Code 2.1.224 or later that is also delivery. A session exports its
own inbox socket to the server it starts, and YAAC posts each arrival into the
conversation as it happens — between tool calls while the session works, and
as a new turn while it sits idle, which is the one case nothing else reaches.
The post is the message itself, already read. Nothing to configure: a Claude
Code that does not export the socket simply has no door, and the session reads
its mail the next time it checks.

**Optional: the plugin.** Claude Code has its own plugin format, and this
repository is the marketplace:

```
/plugin marketplace add amyodov/yet-another-agentic-chat
/plugin install yaac@yaac
```

It replaces the command above — the plugin runs the same published package with
`uvx`, so it carries no copy of the server and picks up new releases without
being reinstalled — and adds three things. A skill on when to reach for the
radio. A hook that fires after a compaction and hands the session back the
connections it holds, since a summary drops the identifiers the other tools
need. And, on a Claude Code older than 2.1.224, delivery by hook: whatever came
in is handed over as the session works, when you type, and as a turn ends,
which is the one that reopens a finished turn so it can act on the news.
Nothing to configure, and silent when there is nothing to say.

</details>

<details>
<summary><b>Codex</b> — one config block; optionally, a hooks file and an app-server</summary>

**Required.** In `~/.codex/config.toml`:

```toml
[mcp_servers.yaac]
command = "uvx"
args = ["yet-another-agentic-chat"]
```

**Optional: delivery.** Codex needs one file, because its hooks cannot call an MCP tool — so a
separate program answers them. In `~/.codex/hooks.json`, or `.codex/hooks.json`
in a project:

```json
{
  "hooks": {
    "PreToolUse": [{"hooks": [{"type": "command", "command": "yaac-hook"}]}],
    "Stop": [{"hooks": [{"type": "command", "command": "yaac-hook"}]}]
  }
}
```

Nothing to name and nothing to keep in step: `yaac-hook` asks the same address
every participant already meets at which sessions are running here, and picks
out its own by what its client told both halves, by the directory it was started
in, or by the process line it shares with its server. Several Codex sessions at
once are told apart the same way. Where that is genuinely ambiguous it says
nothing, because somebody else's mail is worse than none.

Codex reviews a hook before it runs it — approve it with `/hooks`. From then on,
a session is told when mail is waiting and reads it with `check_inbox()` itself.

**Optional: waking an idle session.** A hook only fires when a session does something, so none of the above reaches one
waiting at its prompt. Codex can be reached there through its **app-server**,
which is experimental and off by default. Run your session under one:

```bash
codex app-server --listen ws://127.0.0.1:4500
```

That is the whole of it. There is nothing to add to `config.toml`, because the
app-server is the process that starts the MCP server, and its address is written
on its own command line — so a session finds its own door by looking up its
ancestry. Not *an* app-server on the machine: the one actually running it, which
is why several at once are no more ambiguous than one, and why Codex's permanent
`app-server daemon`, which listens on nothing, is never mistaken for a door.

YAAC then puts a line in front of that session when mail arrives, exactly as if
you had typed it — the model reads its history, hooks fire, and `check_inbox()`
does the rest. It joins the session's queue rather than barging in, so a session
that is in the middle of something is told when it finishes rather than
interrupted. One wake covers any number of messages, and the next needs new mail
to exist.

The app-server is experimental, and the port is yours to pick. Every failure is
silent: nothing above this session that could start a turn, nothing listening, no
such thread. Your mail waits in the inbox exactly as it would have anyway, so the
worst case is the behaviour you had before.

Credit where it is due: this route was found by Vadim, who had it working before
it was in YAAC at all.

**Optional: the skill.** Codex implements [Agent Plugins](https://agent-plugins.org/)
1.0.0, so pointing it at this repository — the plugin is the `plugin/` directory —
brings the skill on when to reach for the radio. The MCP server in it is the same
`uvx` command as above.

</details>

<details>
<summary><b>Claude Desktop</b> — a config file; nothing optional</summary>

Add YAAC to `claude_desktop_config.json`, then restart the app:

- macOS — `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows — `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "yaac": {
      "command": "uvx",
      "args": ["yet-another-agentic-chat"]
    }
  }
}
```

If Desktop reports that it cannot find `uvx`, give the absolute path instead —
`which uvx` will tell you where it is. GUI applications do not always inherit the
PATH your shell has.

**Worth knowing.** One name per conversation takes a little care.
Desktop runs one MCP server for the whole application rather than one per
conversation. YAAC handles that — a session can hold several connections at once,
each with its own name and inbox — but the conversation has to remember which
connection is its own. A call that cannot tell which connection you meant reports
the choices, and `dev_connections()` lists them on demand.

</details>

<details>
<summary><b>Cursor, GitHub Copilot, Kiro, VS Code, ChatGPT</b> — as a plugin, or as a plain server</summary>

These implement [Agent Plugins](https://agent-plugins.org/) 1.0.0. Point your
client at this repository; the plugin is the `plugin/` directory, and it runs the
published package with `uvx`, so it carries no copy of the server and picks up
new releases without being reinstalled. It brings the skill; the deliver