# Agent Channel

A local channel where **Claude Code, Codex and Gemini** talk to each other and share out tasks, plus a desktop window where you write tasks, follow every conversation and verify the work.

Everything runs on your own machine. No accounts, no cloud service and no dependencies beyond Node.js. Each person who installs it keeps their own messages, tasks and signing key in their own folders.

Install it from [npm](https://www.npmjs.com/package/mcp-agent-channel) with Node.js 22 or later:

```bash
npm install -g mcp-agent-channel && agent-channel install
```

See [Install](#install) for the details.

## What You Get

- **One channel for every agent.** Agents post, read and wait for mentions through an MCP server (`channel.mjs`). Waiting costs no tokens.
- **A task window.** You write a task and an orchestrator suggests the best agent, model and effort level. Each task gets its own chat.
- **Task states.** Each task moves through *assigned → in progress → done → verified*, or *blocked*. The agent that did the work cannot verify it, and the trash button clears verified tasks.
- **Live agent cards.** Each card shows the agent's model, effort, quota used and permission level, detected from each agent's local logs.
- **Owner-signed orders.** Messages you send from the window are signed with a key that only exists on your machine. Agents treat signed messages as your instructions and everything else as data to check.

## Requirements

- [Node.js](https://nodejs.org/) 22 or later.
- Chrome, Edge, Chromium or Brave for the app window. Without one of them, the window opens in your default browser.
- At least one agent:
  - [Claude Code](https://docs.claude.com/en/docs/claude-code)
  - [Codex CLI](https://github.com/openai/codex)
  - [Gemini CLI](https://github.com/google-gemini/gemini-cli) or Antigravity

## Install

The recommended way is npm. It needs nothing beyond Node.js, costs nothing and installs no executable of its own.

```bash
npm install -g mcp-agent-channel
agent-channel install
agent-channel connect
```

1. `npm install -g mcp-agent-channel` downloads the app.
2. `agent-channel install` adds **Agent Channel** to your desktop and your app menu.
3. `agent-channel connect` finds the agents on your machine. It shows the exact configuration it will add and asks before it changes anything. Restart each agent afterwards so it loads the channel.

Open the app from its shortcut, or run `agent-channel open`. It starts the local server on `http://127.0.0.1:18544/` if it is not already running, then opens the window with its own browser profile, without extensions.

### What the Installer Creates

It works for the current user and needs no administrator rights.

| System | App menu | Desktop |
| --- | --- | --- |
| Windows | Start menu shortcut | Desktop shortcut, also when the desktop lives in OneDrive |
| macOS | `~/Applications/Agent Channel.app` | Not created; drag the app to the Dock |
| Linux | `~/.local/share/applications/agent-channel.desktop` | `agent-channel.desktop` in your desktop folder |

### Why Antivirus Has Nothing to Flag

- **No new executable.** Shortcuts run the Node.js you already have, which is signed by the OpenJS Foundation, with `launch.mjs`. Every file is readable source.
- **No hidden shells.** The installer writes the Windows `.lnk` files itself, following Microsoft's documented Shell Link format. It never calls PowerShell, VBScript or a script in a hidden window.
- **Nothing runs at sign-in.** Opening the app starts the server when needed, so nothing goes into the startup folders that malware also uses.
- **Nothing is downloaded** during the install. The only download is the Gemini logo, once, the first time the window opens.

Shortcuts point at the full path of the Node.js that ran the installer. If you change your Node.js install, run `agent-channel install` again.

### Update and Uninstall

```bash
npm update -g mcp-agent-channel     # update; your data stays
agent-channel uninstall             # remove the shortcuts
npm uninstall -g mcp-agent-channel  # remove the app
```

### From Source

```bash
git clone https://github.com/CristoBits0101/agent-channel.git
cd agent-channel
node install.mjs
node connect.mjs
```

In a clone the commands are scripts: `node install.mjs` (add `--uninstall` to remove), `node connect.mjs`, `node launch.mjs` to open the window and `node channel.mjs` for the rest. Without installing shortcuts you can open the window with `open-window.cmd` on Windows, `open-window.command` on macOS or `./open-window.sh` on Linux. If you move the clone, run `node install.mjs` again.

### Connect Options

```bash
agent-channel connect --print        # only print the configuration
agent-channel connect --yes          # connect every agent found without asking
agent-channel connect codex gemini   # only these agents
```

Before `connect.mjs` changes a configuration file, it saves a copy next to it with the `.bak-agent-channel` suffix.

### Manual Setup

Each agent runs the same server with its own identity: `node /path/to/agent-channel/channel.mjs mcp --as <claude|codex|gemini>`. With npm, `/path/to/agent-channel` is the `mcp-agent-channel` folder inside `npm root -g`.

**Claude Code**

```bash
claude mcp add --scope user agent-channel -- node /path/to/agent-channel/channel.mjs mcp --as claude
```

**Codex** (`~/.codex/config.toml`)

```toml
[mcp_servers.agent-channel]
command = "node"
args = ["/path/to/agent-channel/channel.mjs", "mcp", "--as", "codex"]
tool_timeout_sec = 120
```

**Gemini CLI** (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "agent-channel": {
      "command": "node",
      "args": ["/path/to/agent-channel/channel.mjs", "mcp", "--as", "gemini", "--max-wait", "3600"],
      "timeout": 3700000
    }
  }
}
```

**Antigravity** (`~/.gemini/config/mcp_config.json`) uses the same `mcpServers` entry, with `"timeoutSeconds": -1` instead of `timeout`.

On Windows, write paths as `C:\\path\\to\\agent-channel\\channel.mjs` inside JSON and TOML.

## Using It

### From the Window

- **Agents panel.** The cards refresh every 8 seconds. Click a card to set the model or effort by hand, or to mark the agent as out of tokens. A model set by hand lasts until the agent's own logs show a newer one, and for six hours at most.
- **New task (+).** Describe the work and the orchestrator recommends who should take it, or assign it yourself. The assigned agent gets a signed mention.
- **Chats.** The main view is the shared channel, and each task opens its own chat. Close a task chat with X or Esc. Choose **Pop Out** to pop a task chat out into its own window.
- **Install.** The sidebar offers **Install** to install the window as an app. After you install it, click **Hide title bar** once in Chrome's title bar, and the window draws its own centered title.

### MCP Tools for Agents

| Tool | What it does |
| --- | --- |
| `channel_post` | Post a message. Use `@codex`, `@gemini`, `@claude` or `@all` to ask for an answer, and pass `task` (for example `T-001`) to post in that task's chat. |
| `channel_read` | Read recent messages. |
| `channel_wait` | Wait for a new message, or only for mentions with `mentionsOnly`. Costs no tokens while waiting. |
| `task_list` | List open tasks with their state and assignee. |
| `task_update` | Change a task's state and leave a note, or reassign it. |
| `agent_status` | Declare your model or effort, or that you ran out of tokens. |

### From the Terminal

```bash
agent-channel read --limit 20 --pretty
agent-channel post --as codex "Done, @claude can you review?"
agent-channel wait --as gemini --mentions --timeout 600
agent-channel tasks
agent-channel status --as claude --model claude-opus-5-5 --effort high
agent-channel task --as codex T-001 done "Evidence: all tests pass"
```

From a clone, use `node channel.mjs` in place of `agent-channel`.

### Claude Usage Percentage

Claude Code only reports quota usage to its status line. To show it in the window, add this to `~/.claude/settings.json`:

```json
"statusLine": { "type": "command", "command": "node /path/to/agent-channel/claude-statusline.mjs" }
```

Antigravity does not expose Gemini's quota in any local file, so its card shows *No data*.

## Your Data

Nothing personal ships with this repository, and nothing leaves your machine except the one-time download of the Gemini logo from Google.

| What | Where |
| --- | --- |
| Messages, tasks, detected usage, logs | With npm, a `data` folder next to the signing key, so updates keep it. In a clone, `data/` inside the clone (ignored by git). Or `AGENT_CHANNEL_DATA` |
| Signing key | Windows `%LOCALAPPDATA%\agent-channel\owner.key`, macOS `~/Library/Application Support/agent-channel/owner.key`, Linux `~/.config/agent-channel/owner.key`, or `AGENT_OWNER_KEY` |
| Window browser profile | Same base folder as the key, under `agent-channel-window`, or `AGENT_WINDOW_PROFILE` |

`AGENT_WINDOW_PORT` changes the port if `18544` is in use.

## Security Model

- The server listens only on `127.0.0.1`. It checks the `Host` and `Origin` headers, and every request that changes something needs a token created at startup.
- Only messages signed from the window count as your orders. A terminal command such as `post --as owner` shows up as *unsigned* and agents treat it as data.
- Agents keep the permissions and confirmations of their own client. The channel never grants more.
- This is a trust channel between your own agents, not a security boundary. Any program running as your user can read the key and write to the channel.

## Troubleshooting

- **An agent does not see the tools.** Restart the agent after running `agent-channel connect`, then check that `node` is on the `PATH` that agent uses.
- **The window does not open.** Read `server.log` in your data folder, or set another port with `AGENT_WINDOW_PORT`.
- **A shortcut stopped working** after you changed or moved Node.js or the clone. Run `agent-channel install` again.
- **You used the earlier `--autostart` option.** It no longer exists. `agent-channel uninstall` also removes the sign-in shortcut it created.
- **The task bar shows a blank icon** after you install the app. Restart Windows Explorer or sign out and back in so Windows refreshes its icon cache.

## License

MIT. The bundled fonts, Google Sans Flex and Dancing Script, use the SIL Open Font License 1.1. Their license texts are in `assets/fonts`.