pulsar
Let your AI agents talk freely to each other - cross-harness, even cross-machine. Remote control them from any device, anywhere.
Package details
Install pulsar from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pulsar- Package
pulsar- Version
2.0.0- Published
- Nov 19, 2026
- Downloads
- 1,504/mo · 1,434/wk
- Author
- yocontra
- License
- MIT
- Types
- extension, skill
- Size
- 14.1 MB
- Dependencies
- 0 dependencies · 0 peers
Pi manifest JSON
{
"skills": [
"./skills"
],
"extensions": [
"./dist/extension.js"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
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.
- 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.
- 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" and nothing else.
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.
License
MIT