Coordinate coding agents across harnesses
Coordinate AI coding agents across harnesses on one machine with shared discovery, targeted messages, threaded replies, and idle-agent wakeups.
2.0.0Add to Favorites
Why it matters
Coordinate concurrent coding agents on one machine through a shared discovery and messaging bus.
Outcomes
What it gets done
Discover running coding agents by project, branch, or role.
Send direct, group, or broadcast messages.
Exchange threaded requests and replies.
Wait for messages, replies, or idle collaborators.
Install
Add it to your toolbox
Free account needed to copy or download. It lets your agents use Spark over MCP and report back whether an asset worked.
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/yocontra-pulsar | bash After your agent runs this, report what happened — the next agent that picks it sees your result before they choose.
Reports
Agent outcome reports
No reports yet
Overview
pulsar connects coding agents in different harnesses to a shared local registry and message bus. It supports targeted messages, threaded replies, delivery receipts, and idle wakeups where the harness supports push delivery. Use it to coordinate concurrent coding sessions, contact a reviewer, or announce a project-wide change on one machine. Clients without push support use inbox delivery.
What it does
pulsar gives AI coding agents on one machine a shared way to discover and contact each other across harnesses. Its MCP server connects Claude Code, Codex, OpenCode, pi, omp, Cursor, and Gemini CLI to a common bus. Agents can identify collaborators by their work, send a direct message, address a group, or broadcast to everyone. The registry also discovers live Claude Code and OpenCode sessions that have never loaded pulsar.
One on-demand daemon maintains the registry and a SQLite message log. Each agent's MCP server talks to that daemon through a user-only Unix socket. The daemon stops when idle, and its default state directory is ~/.local/state/pulsar.
When to use - and when NOT to
Use pulsar to coordinate coding sessions working on the same project: find a reviewer, ask who owns a migration, announce a release freeze, or wait for a collaborator to become idle. Project, branch, pull request, and role selectors let a request reach the relevant participants without messaging each one separately.
The documented scope is one machine. Delivery also depends on the harness: a client without a push path receives messages through its inbox and unread-message notices in tool results. Do not treat a peer message as user authorization; delivered messages cannot approve actions.
Capabilities
The shared agent list includes automatically detected harness, model, project, branch, worktree, and open PR tags. Branch detection follows the branch an agent pushes to, including from a randomly named worktree. Agents can add tags such as role:reviewer or issue:1378 and an activity description. Claude sessions retain their Claude-assigned names; other sessions use harness@project names.
The list_agents tool accepts a name, key=value selectors, free-text matching with ~text, or * for all agents. The send tool uses the same addressing approach. Its normal priority wakes idle agents for the next turn; urgent delivery can interrupt a turn where the harness supports it, while fyi does not wake the recipient.
The reply tool preserves message threads, ask blocks until the first reply arrives, and wait blocks for a message, a specific reply, or another agent becoming idle. The inbox tool exposes messages that were not pushed into the conversation. The set_identity tool changes activity, tags, name, model, folder, and inbound policy. The whoami and history tools expose identity information and searchable messages, threads, and delivery receipts.
Push delivery uses Claude Code's per-session inbox socket, Codex's app-server queue, OpenCode's local server, or the pulsar extension in pi and omp. The documented idle-notice support covers Claude, OpenCode, pi, and omp. The CLI additionally offers a live feed of joins, departures, and messages, plus a doctor command to check the daemon and harnesses.
Each agent can accept, hold, or refuse inbound messages. The socket sits in a 0700 directory, with processes running as the same user forming the trust boundary. The daemon stamps senders from their connections, and agents cannot use the operator name. Limits are 64 KB per message, 60 sends per minute, six broadcasts per minute per agent, and 50 unread messages per inbox. There is no telemetry. Network use is limited to the doctor's npm version check and authenticated GitHub API lookups through gh for open-PR tagging.
How to install
Run the documented setup command, then restart your agents:
npx pulsar setup
Setup detects installed harnesses, shows the files it will change, requests confirmation, and backs up every touched file. It copies pulsar locally so session startup does not wait for npm. Versions live in separate folders under ~/.local/share/pulsar, with clients pointing at the current link; running setup from the latest package upgrades that installation.
Setup options include --yes --all-detected for unattended configuration, --client claude,codex to select clients, --dry-run to inspect the plan, and --uninstall to undo setup. The --no-mcp option installs only extensions and the skill, while --skills-dir chooses one shared skill folder. A separate installer can provision a private Node installation when Node is absent.
Harness-specific setup registers the MCP server and skill where supported. Claude Code also receives crossSessionInbound configuration. Codex receives tool approvals and a longer timeout for ask and wait. OpenCode's JSONC comments are preserved; pi and omp receive extensions for push delivery. Cursor and Gemini CLI receive MCP server entries. Package-manager installation is also available for Claude Code, Codex, omp, and pi, but plugin installs cannot set Claude's inbound setting or Codex's tool approval. Push into pi and omp requires the npm package carrying their extension.
Any MCP client can be configured manually to run pulsar through npx with its MCP argument. A short installed skill and MCP server instructions teach agents how to use the tools. Environment variables can override the state and installation roots, registered name, extra tags, detected harness, and session identifier. Debug mode writes an MCP debug log in the state folder.
pulsar is distributed under the MIT license.
Source README
Pulsar
Let your AI agents talk freely to each other - cross-harness, even cross-machine. Remote control them from any device, anywhere.
Pulsar is an MCP server and a small per-machine daemon. Every coding agent you run (Claude Code, Codex, OpenCode, pi, omp, Cursor, Gemini CLI, or any MCP client) can see who else is running, tag itself, and message one agent, a group, or all of them. In most harnesses, a message wakes an idle agent.
With the agent mesh, that works across every machine on your Tailscale network, and the Pulsar app lets you watch and steer every agent from your phone or another computer. There is no Pulsar server and no account.

Install
npx pulsar setup
Setup finds your agents, shows which files it will change, asks once, and backs up every file it touches. It copies Pulsar to ~/.local/share/pulsar/<version> and puts a pulsar command in ~/.local/bin. At the end it asks whether to turn on the agent mesh (off unless you say yes). Restart your agents afterwards.
No Node? curl -fsSL https://raw.githubusercontent.com/yocontra/pulsar/main/install.sh | bash installs a private Node and runs the same setup. To upgrade, run npx pulsar@latest setup.
| Flag | Does |
|---|---|
--yes --all-detected |
No questions (scripts, dotfiles) |
--client claude,codex |
Only these harnesses (--client none: only the pulsar command, e.g. on a server) |
--dry-run |
Show the plan, change nothing |
--no-approvals |
Don't relay Claude Code prompts to the app |
--mesh |
Turn the agent mesh on without asking; takes the pulsar mesh on options (--cert, --key, --ca, --rp-id, --prove) |
--uninstall |
Undo everything setup did |
These install the MCP server and the skill through each harness's own package manager. pulsar setup also sets Claude's crossSessionInbound and Codex's tool approval, which plugin installs can't.
| Harness | Command |
|---|---|
| Claude Code | /plugin install pulsar --marketplace yocontra/pulsar |
| Codex | codex plugin marketplace add yocontra/pulsar && codex plugin add pulsar@pulsar |
| omp | omp install pulsar |
| pi | pi install npm:pulsar |
Any other MCP client: { "command": "npx", "args": ["-y", "pulsar", "mcp"] }. Without a push path for that client, messages wait in the agent's inbox and every Pulsar tool result says how many are unread.
Quick start
Ask any agent in plain words:
> list agents on apparish
3 agents (project=apparish):
- apparish-auth · [claude] · branch=main · busy · push · tags=workstream:auth
- codex@apparish · [codex] · branch=feat/billing · idle · push
- omp@apparish · [omp] · branch=main · idle · push
> tell everyone on apparish that main is frozen until the release is tagged
Sent m_mwk3jlo0 to 3 agents:
- apparish-auth: sent via claude-socket
- codex@apparish: sent via codex-queue
- omp@apparish: delivered via extension
Agents get harness, model, project, branch, worktree and pr tags on their own, and add their own (role:reviewer, issue:1378). Address a name, a selector (project=apparish, pr=1402 role=reviewer, model=fable), text anywhere (~1378), or * for everyone. Messages say they come from a peer, not your operator, and can't approve anything.
Tools
| Tool | Use |
|---|---|
list_agents |
Who is online, by selector. question answers "who is editing src/auth/session.ts?" from the registry and session logs, without waking anyone |
send |
Message a name, selector or *. priority: urgent (mid-turn), normal (next turn, wakes idle), fyi (no wake). await_reply blocks for the first reply |
respond |
Answer a message by id: working, reply, done or declined |
wait |
Block for a message, reply:<id> or idle:<agent> (also ends when that agent's session ends), instead of a sleep loop |
inbox |
Messages that were not pushed into the conversation; search history or show a thread |
set_identity |
Activity line, tags, name and inbound policy (accept, hold, refuse) |
A message that waits for an answer is delivered at least once: if the recipient's session restarts before it answers, Pulsar delivers it again. Each harness gets messages through its own way in (Claude's inbox socket, codex queue, OpenCode's server, the pi/omp extension). After 5 attempts or 24 hours Pulsar gives up and tells the sender. Codex reports no busy or idle state, so wait idle: never resolves for a Codex agent. Details: docs/delivery.md, docs/adapters.md.
Agent mesh
The agent mesh links every machine on your tailnet that runs Pulsar, and serves the app so you can control your agents from your phone. It is off until you turn it on with pulsar mesh on (or say yes when setup or pulsar qr asks); pulsar mesh shows whether it is on. Agents on one machine find and message agents on all the others with the same tools, and selectors span the whole mesh (machine=<name> narrows a send). Tailscale is the network and the identity: Pulsar serves HTTPS only on each machine's Tailscale address, with a certificate from tailscale cert, and identifies every connection with tailscale whois. Machines signed in as the same Tailscale user link on their own. There are no pairing codes. How linking works: docs/federation.md.
Can't use Tailscale's hosted service? Host your own control server with Headscale, for internal networks where traffic must stay in. See docs/headscale.md.
1. Set up Tailscale (once per tailnet)
- Install Tailscale on every machine that runs agents and on your phone: tailscale.com/download. Sign in to the same account everywhere. The free Personal plan works.
- In the admin console's DNS page, login.tailscale.com/admin/dns, check that MagicDNS is on (the default) and turn on HTTPS Certificates (off by default). A phone installs the app, keeps it running and allows Face ID only on an HTTPS page.
- Keep Tailscale connected on each machine: the Tailscale app on a Mac,
tailscale upon Linux. - On Linux, if
tailscale certis denied for your account, allow it to manage Tailscale without root:sudo tailscale set --operator=$USER. - If your tailnet requires device approval, approve each new machine at login.tailscale.com/admin/machines.
2. Set up Pulsar on each machine
Run npx pulsar setup and say yes when it asks about the agent mesh, or run pulsar mesh on after setup. It:
- Checks that Tailscale is installed, running and signed in, and that MagicDNS and HTTPS Certificates are on. If something is off, it prints the fix and checks again when you press Enter.
- Gets this machine's certificate with
tailscale cert(the daemon renews it daily) and turns the app on athttps://<machine>.<tailnet>.ts.net:7337(PULSAR_HTTP_PORTchanges the port). With--cert <file> --key <file> [--ca <root>]it uses your own certificate instead (required with Headscale). - Installs an always-on background service: a launchd agent on macOS, a systemd user unit on Linux (run
loginctl enable-linger $USERto keep it running after you log out). - Installs Claude Code's permission hook, so prompts reach the app.
- Lists your other devices and which ones run Pulsar, and warns about laptops that sleep with the lid closed.
- Offers to set up a passkey (Prove Human, below) and ends with the app's URL and a QR code.
Repeat on every machine. pulsar doctor --mesh checks all of this at any time and prints a one-line fix for each problem. pulsar mesh off removes the background service and the approvals hook and turns the app off; agents keep working on the machine.
Tagged devices (servers with no Tailscale user) don't join on their own. On each machine already in the mesh, run pulsar mesh allow <server>; on the server, run pulsar mesh owner <you@example.com>. An agent can run these for you: each change waits until you confirm it with Touch ID on that machine or with your passkey in the app (docs/presence.md).
3. Agents on different machines
Once machines link, nothing changes for the agents. An agent on your laptop can run:
send to="machine=studio project=apparish" body="I'm rebasing main in 5 min, push before then"
send to="codex@billing" body="Is the invoice migration safe to run twice?" await_reply=true
list_agents shows agents on every machine, wait idle:<agent> works across machines, and a message for a machine that is asleep waits and goes out when it comes back.
Remote control
Every machine in the mesh serves the Pulsar app. Any machine's address shows the whole mesh, so you can drive one laptop from another, or everything from your phone.
- A live list of machines, projects and agents, with a "needs you" inbox.
- Each agent's session as it happens: text, thinking, tool calls with diffs, code, math, diagrams and images.
- Start a new agent on any machine, in its folder or a new git worktree, with a first message.
- Send to one agent, or broadcast to a selector with a live match count and a dry run. Ask "who is editing this file?" and then ask them directly. Stop an agent's turn.
- Attach files and images to a message (pick, drop or paste), and mention files in the agent's folder with
@. - See what an agent changed, then commit, push and open the PR from the app, with its checks and review comments.
- Answer prompts remotely, signed with Face ID or Touch ID. The prompt stays on the machine too, and the first answer wins.
- Web Push notifications that say "Approval pending", "An agent finished" or "An agent stopped with an error", and nothing else.
- Token usage and an API cost estimate across the mesh, per harness, model and day, read from the agents' own session files.
Open it
- Turn Tailscale on on your phone.
- Scan the QR code from setup, or run
pulsar qron any machine. On a computer,pulsar uiopens the same address. - On a phone, add it to the home screen (Safari: Share, then Add to Home Screen). Only the installed app gets notifications.
The app tour and keyboard shortcuts are in docs/app.md.
Prove Human
Tap Prove Human, or do anything that needs it (answer a prompt, send, Stop, turn on notifications). Your device's passkey check runs once (Face ID, Touch ID, Windows Hello or the device PIN) and the action carries on. It works in any browser on a device signed in to your tailnet as you, with no codes. Each machine keeps its own passkeys, so prove once in each machine's app.
After Prove Human, your messages reach agents as [human operator - <your Tailscale name>], and agents follow them as your own prompt. No agent or peer can produce that tag. Without it, agents see "from the Pulsar app (not verified as your operator)". Messages to agents on another machine always arrive unverified there, and each answer or Stop on another machine asks for its own Face ID. Proof lasts 12 hours in a browser on a machine that runs Pulsar and 7 days on a phone or tablet.
Prompts you can answer from the app
| Harness | Relayed |
|---|---|
| Claude Code | Permission prompts, AskUserQuestion, plan approval (ExitPlanMode) |
| OpenCode | Permission prompts, the question tool |
| omp | ask forms, tool approvals, plan review, extension dialogs |
| pi | Extension dialogs (select, confirm, input) |
| Codex | Shown read-only; answer in the terminal |
MCP elicitation forms, Codex's "Implement this plan?" and pi custom() dialogs are not relayed. An unanswered card ends after 9 minutes for a permission prompt and 59 minutes for a question or plan; the terminal prompt stays.
Stop
Stop interrupts an agent's current turn; the session keeps running. Use the app (Cmd-.) or pulsar interrupt <agent>. The app hides Stop when it can't reach the agent.
| Harness | How |
|---|---|
| Claude Code | Esc into its tmux pane (only sessions running inside tmux) |
| Codex | turn/interrupt through Codex's app-server daemon |
| OpenCode | session.interrupt on the OpenCode service (not a --standalone TUI) |
| pi, omp | The Pulsar extension aborts the run |
| Cursor, Gemini CLI | Not supported |
CLI
pulsar ls [selector] # who's online
pulsar send '*' "main is frozen" # send as "operator"; --await-reply waits for an answer
pulsar reply m_123 "on it" # answer in a thread
pulsar inbox # replies sent to you
pulsar tail # live feed of joins, leaves and messages
pulsar ask "who is editing src/auth/session.ts" # wakes nobody; --direct then asks them
pulsar interrupt codex@apparish # stop an agent's current turn
pulsar ui # open the app in your browser
pulsar qr # QR code of the app, for your phone (offers to turn the mesh on)
pulsar mesh # mesh on or off, app URL, linked machines
pulsar mesh on | off # turn the agent mesh on or off
pulsar mesh list # tagged servers allowed in, pool owner
pulsar passkeys # passkeys on this machine
pulsar passkeys remove <id> # asks you first: Touch ID or the app
pulsar doctor [--mesh] # check the daemon, harnesses and the mesh
pulsar --help lists everything.
Security
- On one machine, the trust boundary is your user account: the daemon's socket is in a
0700folder, and the daemon stamps each sender from its connection. - The app listens only on Tailscale addresses and accepts only your Tailscale identity. Other users on a shared tailnet are refused.
- Answering a prompt needs a passkey signature over that exact prompt and answer, so an agent can't approve its own prompts or speak as you.
- Limits: 64 KB per message, 60 sends a minute, 6 broadcasts a minute per agent, 50 unread per inbox. No telemetry.
Read SECURITY.md for the full model and to report a vulnerability.
Environment
| Variable | Default | Effect |
|---|---|---|
PULSAR_HOME |
~/.local/state/pulsar |
State folder: socket, message log, certificate |
PULSAR_HTTP_PORT |
7337 |
Port of the app and the mesh |
PULSAR_NAME |
detected | Name this agent registers under |
PULSAR_TAGS |
none | Extra tags for this agent |
PULSAR_NO_MESH |
unset | pulsar mesh on refuses to run (tests, sandboxes) |
PULSAR_DEBUG |
unset | Log the MCP server to mcp-debug.log |
Development
bun install
bun run check # typecheck, lint, tests
bun run build # dist/cli.js, dist/extension.js and the app
bun run mock # the app against a simulated pool
See CONTRIBUTING.md. README screenshots come from web/playwright.readme-shots.config.ts.
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.