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

Motivations

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

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.

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

Install

git clone https://github.com/ivanmak/whatsagent.git
cd whatsagent
bun install

Optional — register the whatsagent CLI globally so you can run it from any directory:

bun link

First setup

Boot the daemon (defaults to http://127.0.0.1:4017, daemon home at ~/.whatsagent/):

bun src/cli.ts start
# or, if you ran `bun link` above:
whatsagent start

The daemon prints the localhost URL. Open it in your browser.

Web UI authentication

The first time you open the web UI, WhatsAgent walks you through setting a password (argon2-hashed, stored in the daemon-global SQLite). Subsequent loads require that password; sessions are cookie-based. Change it later from Settings → Account → Change password. There is no anonymous mode.

If you need to reset the password (forgot it, want to wipe), stop the daemon and clear the auth_users table in ~/.whatsagent/daemon.sqlite, or wipe the daemon home entirely (see Data and Storage).

Configuration

[ui]
host = "127.0.0.1"
port = 4017
allow_hosts = ["https://whatsagent.proxy.example.com"]

Creating Workspace and Agent

In the web UI:

1. Open the workspace switcher in the sidebar and + Add Workspace (give it a name and Kanban prefix, e.g. ALP).
2. On the Agents page, click + Add Repository and point it at any absolute path on disk.
3. Click + Add Agent under the repo, pick a name, choose a runtime (Claude Code / Codex / OpenCode / Pi), assign one or more roles, and Launch.
4. Mark one agent as main from its overflow menu (Star topology default).
5. Open the Messages page to start chatting with the main agent — your messages route as human-web.

Stop the daemon with bun src/cli.ts stop (--all also kills managed runners).

Roles and MCP tool visibility

The roles you assign to an agent decide which MCP tools the agent sees and which actions the daemon will accept from it. RBAC is enforced server-side; the visible tool surface is filtered per-agent at MCP register time and re-checked on every tool call. An agent can hold multiple roles — the union of their grants applies.

Built-in roles ship with sensible defaults:

Roles can be re-assigned later from the agent's edit dialog; the agent's MCP server picks up the new tool surface on its next register (next launch / re-attach).

Detailed RBAC reference (full grant matrix, custom-role authoring, soft / enforce / off modes, daemon-wide ceiling) will land as separate docs in a later release. For now, the source of truth is src/db.ts BUILTIN_ROLE_DEFINITIONS.

Data and Storage

All state lives under WHATSAGENT_DAEMON_HOME (default ~/.whatsagent/):

~/.whatsagent/
  daemon.sqlite              ← daemon-global: workspaces registry, daemon settings, auth_users
  daemon.toml                ← optional static config (UI host/port, host allow-list)
  logs/
    daemon.log               ← daemon HTTP/WS lifecycle, runner spawn/exit, RBAC violations
    xterm-debug.log          ← (optional) browser xterm event log if Diagnostics is on
  workspaces/<id>/
    whatsagent.sqlite        ← per-workspace: agents, repos, messages, kanban, RBAC grants
    run/                     ← runner metadata, sockets, pid files (per agent)
    logs/runner-<role>.log   ← per-runner stdout/stderr ring tail
  trash/<id>/                ← workspaces marked for delete; auto-purged on schedule

Backup: copy the ~/.whatsagent/ tree while the daemon is stopped. SQLite WAL-checkpointed on graceful shutdown, so a hot copy after whatsagent stop is consistent.

Wipe a single workspace: from the web UI sidebar → workspace menu → Delete. The DB moves to ~/.whatsagent/trash/<id>/; an auto-purge timer removes it later.

Wipe everything (full reset): stop the daemon, then rm -rf ~/.whatsagent/. Restart the daemon and you'll be re-prompted for an initial password.

Reset only the password: stop the daemon → delete the row from auth_users in daemon.sqlite (sqlite3 ~/.whatsagent/daemon.sqlite "DELETE FROM auth_users") → restart. Next web visit walks you through password setup again.

Terminal transcripts are intentionally not persisted — only the rolling output tail per runner is held in memory and dropped on runner exit.

MCP Tools

The daemon exposes a curated tool surface per agent over MCP. The visible set depends on the agent's RBAC roles. The MCP server is bound per agent at launch via bun src/cli.ts mcp <workspace>:<repo>:<agent> (or via the runtime plugin injected by the daemon). The schema is the source of truth — every tool returns Zod-validated input + structured JSON output.

Known Limitations

• No Windows support. ConPTY paths in node-pty aren't wired through. Linux + macOS only in v0.1.0.
• Single-user, single-host. No multi-tenant isolation; daemon assumes the local user is trusted (see SECURITY.md threat model).
• Terminal transcripts not persisted. Only the rolling output tail (default 4000 events / ~400 KB) is kept per runner; full history is lost on runner exit.
• One active writer per agent. Re-launching an agent evicts the previous session (the previous writer can no longer post input).
• Codex push messaging is manual. Codex does not support native push messaging, and requires the user to forward the inbox-nudge prompt manually (the UI will allow user to insert prompt via shortcut).

Troubleshooting

Cannot start agent session on macOS Bun's tarball extraction strips the execute bit from node-pty's spawn-helper prebuild. Re-run bun install (the postinstall script applies chmod +x automatically), or one-shot:

chmod +x node_modules/node-pty/prebuilds/darwin-*/spawn-helper

Runtime not detected (claude / codex / opencode / pi) Check that the binary is on the daemon's PATH. Settings → Runtimes shows the resolved path and version. If your shell rc adds the runtime to PATH, you must launch the daemon from that shell — ~/.zprofile/~/.bash_profile is read at login, but a daemon started from a tool like launchd won't see it.

Port 4017 already in use Another process owns the port. whatsagent stop (or lsof -i :4017 to find the squatter). Override with WHATSAGENT_PORT=5000 whatsagent start, or change the port in ~/.whatsagent/daemon.toml.

Roadmap

• More documentations
• Per-agent prompts
• Integrations with other coding-agent runtimes
• Export of Kanban and Epic data (CSV / JSON / Markdown)
• UI improvements
• Multi-channel support (schema already in place)

Built With

Inspirations:

• claude-peers-mcp by Louis V — earliest version of the agent-peer concept on Claude Code.
• agent-peers-mcp by Co-Messi — the immediate predecessor whose limitations motivated this project.

Contributing

See CONTRIBUTING.md for branching, commits, and review expectations.

License

MIT — see LICENSE.

Disclaimer

This project does not come with warranty, and is not intended to be accessible from the Internet. When allowing coding agents to communicate, you are still responsible of overseeing and managing their activities. I'm not responsible to any adverse outcomes arising from using WhatsAgent, including but not limited to agents consuming extra tokens, unintended code written without your approval, or overclocking your GPU.