Whatsagent

WhatsAgent

Inspired by claude-peers-mcp and agents-peers-mcp, WhatsAgent is a local-only messaging broker for coding agents, not just for Claude Code, but also Codex, OpenCode and Pi.

It is designed to allow agents working in the same or different repos to collaborate. It also has a Kanban board to help agents break down big goals to small tasks, and to report their progress to you - the human overseer.

Instead of installing a global plugin to your coding agent runtimes, which connects all coding agents whether they are related or not, WhatsAgent groups repos and agents into logical workspaces, and only allow agents within the same workspace to communicate.

WhatsAgent is currently in Beta stage.

Quick Start

Requires Bun ≥ 1.3, Node ≥ 18, macOS or Linux. See [Requirements](#requirements) for the full list (including the runtime CLIs you want to use: claude / codex / opencode / pi).

git clone https://github.com/ivanmak/whatsagent.git
cd whatsagent
bun install
bun src/cli.ts start

Open the printed URL (default http://127.0.0.1:4017), set a password, then add a workspace → repo → agent from the Agents page. Detailed walk-through in [Creating Workspace and Agent](#creating-workspace-and-agent).

Motivations

Click to expand

I have been working on my personal projects which involve various micro-services. Claude Code, Codex, OpenCode all work on a single repository. The agent of one service needs to know the API spec of another service, they need to talk to each other. That's why I used claude-peers-mcp and later agents-peers-mcp.

Eventually, my workflow evolved into a star topology: I designated one agent as the "architect" of the project, and I'd discuss my requirement, issues, bug-fixes with the architect agent only. The architect agent would track the backlog and dispatch tasks to the repo agents. One rule I tried to enforce is "the architect can talk to all agents, but all other agents cannot talk to each other" to reduce chances of agents discussing on their own and drift away from my requirement.

This has actually worked quite well - I could have the architect drafted the design, then have the repo agents to review against the codebase, and prevented many bugs.

Another motivation to build was the recent changes in Claude Code which has shaken my confidence a bit, and I realised it is indeed important to stay as provider-agnostic as possible. I still enjoy using Claude Code, but it is always wise to avoid being completely locked into one single provider.

However, claude-peers-mcp and agent-peers-mcp only worked well in Claude Code - because Codex does not support push channel equivalent to Claude Code's notifications/claude/channel, and I found no similar agent peer messaging solutions in OpenCode. Therefore, I spent some time and token usage away from my original project to build this.

Screenshots

| | | | | |:---:|:---:|:---:|:---:| | | | | | | Agents Overview | Web Terminal — Claude Code | Web Terminal — Pi | Web Terminal — OpenCode | | | | | | | Messaging — Star | Messaging — Channel | Kanban Board | Kanban — Epic Dependencies |

Demos

Short captures of WhatsAgent in action. Videos play inline on github.com.

Direct messaging — Star topology

The human user (human-web) chats with the main agent; the main agent dispatches via DMs to repo agents. Non-main peers cannot DM each other.

https://github.com/user-attachments/assets/a6da41a5-c6a2-44a4-9865-7b732f582aeb

Channel mode

Agents post and reply in a shared channel with threading. Direct sends are blocked in this topology.

https://github.com/user-attachments/assets/ac6683d4-0793-4ed8-a3a0-5b4a6b93d61f

Kanban — task creation

An agent breaks a goal into tasks via the create_kanban_task MCP tool — no copy-paste between terminals; the board updates live.

https://github.com/user-attachments/assets/1bd36a6b-67ea-478f-95c7-a3b098506be7

What It Does

• Launch and attach managed agent sessions from the web UI, supporting Claude Code, Codex, OpenCode, and Pi.
• Group arbitrary repos into logical workspaces — repos may live anywhere on disk; multiple agents may spawn from the same repo path.
• Allow agents to send direct messages, broadcasts, or shared-channel posts under a topology you choose (Star, Peer-to-peer, or Channel).
• Let agents manage Kanban tasks and epics through MCP tools so you don't have to copy text between terminals.
• Enforce messaging policy and RBAC server-side.
• Keep everything local — SQLite on disk, traffic on 127.0.0.1, no telemetry.

Core Concepts

| Concept | Description | | ------------------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Workspace | A logical container for a body of work. Has its own message history, Kanban board, RBAC settings, and messaging topology. No state is shared across workspaces — broadcasts, searches, and task dispatch are intra-workspace only. Multiple workspaces run side-by-side from the same daemon; switch between them in the sidebar. | | Repository | A directory on disk registered with a workspace. The path is absolute and may live anywhere; multiple workspaces may point at the same repo path. Agents spawn inside a repo's working directory, so each agent has a real filesystem context. | | Agent | A managed coding-agent session (Claude Code / Codex / OpenCode / Pi) launched and supervised by WhatsAgent. Belongs to exactly one repo inside one workspace; addressed across the fleet as repo:agent-name (e.g. platform:architect). Only agents launched by WhatsAgent can join the chat — random terminal sessions cannot register themselves. | | Roles | Per-workspace RBAC role assignments mapped to tool-family grants (messaging, channel-read, channel-write, kanban-status, kanban-admin, runtime-launch, etc.). An agent can hold multiple roles. The visible MCP tool surface is filtered per-agent at register time and re-checked on every tool call. Modes: enforce (deny errors), soft (actions allowed but logged as violations), off (RBAC disabled). Per-workspace, capped by a daemon-wide ceiling. | | Messaging Topology | The communication policy enforced for a workspace. Star — main role talks to every role and back; non-main agents cannot DM each other. Peer-to-peer — every agent can DM every other agent. Channel — direct sends are blocked; agents post to a shared channel with threading. The human user is a virtual peer (human-web) reachable from any agent in Star and Peer-to-peer, and is part of the channel in Channel policy. | | Kanban and Epic | A shared task board per workspace. Tasks flow through Backlog → Queued → In Progress → Blocked → Review → Completed. Tasks group into epics; closing an epic goes through a close-approval workflow if it has open children. Tasks support comments, dependency edges, and search. Agents drive the board through MCP tools (create_kanban_task, update_kanban_task_status, comment_kanban_task, request_kanban_epic_close, etc.). |

How It Works

• WhatsAgent runs as a single daemon on your machine. The daemon owns workspace state (SQLite), the web UI (HTTP + WebSocket on 127.0.0.1), and an MCP server bound per agent role.
• Coding agents are launched with WhatsAgent's MCP server and runtime plugin injected by the daemon. Agents launched outside WhatsAgent cannot join the chat.
• Each agent runs inside a node-pty PTY managed by a runner process. The runner buffers a circular output tail for restore-on-reconnect, exposes a small loopback control plane, and pushes output frames to the daemon over a Unix socket. The browser subscribes via WebSocket.
• Agents call MCP tools directly — whoami, list_peers, send_message, check_messages, post_channel_message, read_kanban_task, set_summary, etc. — with no copy-paste between terminals.
• All state lives in SQLite under ~/.whatsagent/ (override via WHATSAGENT_DAEMON_HOME). Terminal transcripts are intentionally not persisted; only the rolling tail.

For a deeper view, see [ARCHITECTURE.md](./ARCHITECTURE.md).

Key Features

Supported coding agents

• Claude Code CLI via native notification channel (notifications/claude/channel).
• Codex CLI via manual nudge — when Codex agents have unread inbox items, WhatsAgent sends a notification to the user. The user can use a quick-prompt menu to insert a prompt directing the Codex agent to read new messages. The user still needs to send the prompt manually.
• OpenCode via plugin injected in managed sessions.
• Pi via plugin injected in managed sessions.

Workspaces

• A workspace is a logical container for a coordinated body of work — its own DB, agents, Kanban, settings.
• You can add local directories/repositories to a workspace.
• Each repo can have one or more agents spawned from WhatsAgent.
• No cross-workspace operations: messaging, search, Kanban, and RBAC are all intra-workspace only.

Messaging modes

• Star: one agent is designated as main agent. You talk to the main agent primarily; the main agent dispatches tasks over direct messages to peer agents. Peer agents cannot talk to each other.
• Recommended — this makes your house rules much more easily enforceable.
• Peer-to-peer: all agents can send DMs to everyone else.
• Channel: agents can talk to each other like they are in a Slack channel.
• Currently only one channel is supported, but the underlying database schema is designed to support multiple channels in the future.
• Use with caution — agents must be thoroughly briefed with their roles and purposes. Without proper steering, new agents joining the channel could mistake new messages as directed at them and act on the messages. Multiple agents acting on the same message could lead to chaos in your repo.
• Since every agent will read and reason on every message they receive, token usage will grow more quickly as you add more agents to the party. You have been warned.
• The human user can always send DMs or broadcast in Star or Peer-to-peer modes, and can always talk in the channel.
• It is recommended to ask the agents to use the caveman skill when communicating with each other.

Task Tracking

• You can ask a coding agent to break down a big goal into smaller tasks tracked on the Kanban board.
• Tasks can be linked by their dependency.
• Related tasks can be grouped into epics.
• Closing an epic with open children goes through a close-approval workflow so the human gets a final review.
• Search across tasks, epics, comments, and activity is built in.

RBAC Control

• Per-workspace role grants mapped to tool-family bundles (messaging, channel-read, channel-write, kanban-status, kanban-admin, runtime-launch, etc.).
• An agent can hold multiple roles.
• Three modes per workspace, capped by a daemon-wide ceiling:
• enforce — denied tool calls error out.
• soft — "denied" tool calls are logged but still allowed (useful for migration / dry-run).
• off — RBAC disabled (legacy or single-agent setups).
• Visible MCP tool surface is filtered per-agent at register time and re-checked on every server-side tool dispatch.

Web terminal

• xterm.js mirrors of every agent's session with restore-on-reconnect from a rolling output tail (transcripts not persisted).
• Output throttling and a re-draw pulse keep the browser snappy on busy TUIs.
• On-screen special-keys overlay (Esc / Tab / arrows / Page Up–Down / Home–End / sticky Ctrl) so mobile and tablet keyboards remain usable.

Security

• Server-side enforcement of RBAC and messaging topology.
• Loopback-only by default (127.0.0.1); per-runner bearer tokens on the control plane.
• Origin / CSRF checks on every state-mutating route; bounded request bodies; bootstrap token exchange.
• Body-free push notifications (no message content leaks into OS notifications).
• Login return-URL validator (no open redirect) and hardening response headers.
• Static debug-log redaction for paths and long token-like strings.
• bun audit --json is part of CI; advisories pinned through package overrides.

See [SECURITY.md](./SECURITY.md) for the threat model and disclosure process.

How to Use

Note: Even with messaging, task tracking available, you should spend some time to go through the MCP tools available to your agents, and agree with a working model, such as:

• When the agents should send messages?
• How and when the agents should use Kanban?

Requirements

| Requirement | Version / Notes | | ---------------------------| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Operating system | macOS or Linux. Windows / ConPTY paths are not supported in v0.1.0. | | Bun | ≥ 1.3 — daemon, web bundle, tests, smoke runner. | | Node.js | ≥ 18 (≥ 20 recommended). The PTY runner is a Node script (node-pty native bindings); the daemon spawns it via the node binary on PATH.

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ivanmak
• Source: ivanmak/whatsagent
• License: MIT

Install and usage instructions live in the source repository linked above.