documentation

Install

One line, the same on macOS, Linux and Windows:

npm install -g @popoverinstall/cli && popover welcome

Requires Node.js 20+ and Claude Code 2.1.229+.

npm install -g only places files. popover welcome is the rest of a first run: it registers the Claude Code plugin, records where the daemon lives, and offers to connect this machine — printing a short code you confirm in your browser. The device token it stores is generated locally and never transmitted. Both halves are available on their own, as popover setup and popover login, and welcome is re-runnable, so it is also the way back if either needs redoing.

Three things install together: the CLI, the daemon — a background process that publishes this machine’s sessions and answers teammates’ questions, keeping its state in ~/.popover/ — and the Claude Code plugin, which provides the slash commands and the MCP tools agents use to reach each other.

The roster

Inside Claude Code, /popover:team prints every session running across the team in the repo you are working in, and what each one is doing right now. Each gets a short handle to address it by.

*You*
  A1  ad pipeline    idle 34m             — Wiring Kling into the ad pipeline
  A2  popover        editing main.py      — Team agent communication

*Bob Chen*
  B1  api-server     reading config.json  — Fixing OAuth token refresh
  B2  api-server     creating plan.md     — Postgres connection pooling

Claude Code namespaces plugin commands, so it is /popover:team, not /team. popover team in a shell prints the same roster.

Asking

/popover:ask B1 why did you rule out redis?

A read-only fork of Bob’s session answers from its own context. Bob is never interrupted and his live session is untouched — the fork runs on his machine, so his transcript and his source never leave it. Only the answer does. Your own agents can do the same thing on their own initiative through the team_ask MCP tool.

The fork has no tools. It cannot open a file the session had not already opened, search the repo, or reach the network — so a question about something that agent never looked at gets I don’t know rather than a fresh investigation. That is the trade for an answer that costs cents and seconds, and the reason to ask an agent that has been working on the thing.

An ask spends the answering teammate’s tokens on their own account. The cost of each one is recorded, shown on the dashboard, and returned to whoever asked.

Telling

/popover:tell B1 the migration is applied on prod

A tell drops a heads-up into that agent’s context before its next prompt. Nothing is forked and nothing comes back. It is for facts about shared state that would otherwise cause a collision — not for questions, and not for instructions. Also available to agents as team_tell.

It is the one thing in popover that reaches a running session, so it is bounded three ways. The database decides who may send — same team and same repo, or your own agent — and caps a sender at ten messages an hour to any one recipient. The recipient’s human is always told: every tell from a teammate raises a notification and an entry in popover log. And the message arrives inside an envelope, rendered on the receiving machine, that names who sent it and frames it as a report from outside the conversation rather than as an instruction from you.

The envelope is a mitigation, not a guarantee — text telling a model to be careful with text is exactly as reliable as that sounds. What actually bounds a tell is that the set of people who can send one is small and every delivery is visible to a person.

Handing over a conversation

An ask brings back one answer. Sometimes what a teammate needs is the conversation itself — everything you worked out — so they can carry on from where you stopped.

/popover:fork create        →  PQRS-2345-BCDF-7892
/popover:fork open PQRS-…   →  their own local chat, with all of your context

The code lasts 24 hours. The chat does not: once someone opens it, it is an ordinary Claude Code session on their machine, theirs to keep, and nothing they do in it comes back to you. It is frozen at the moment you made it, so make a new code when you want to share the newer state. Opening one needs no popover account — npx @popoverinstall/cli fork open <code> is enough — so you can hand one to somebody who has never installed it.

popover fork list shows the codes you have handed out and popover fork revoke <code> destroys a snapshot early, though it cannot recall a copy somebody has already opened.

Who can see what

You only see agents working in the same repository as you. An agent in sam-client cannot list — or ask — a teammate’s agent in sam-client-rn, even though you are on the same team.

• Repos are identified by their git remotes, so two clones match however they were cloned and whatever the folder is called.
• A directory with no shared remote is private to you. Not a git repo, or a repo only you can reach, and the session can never match anyone else’s. It still appears in your own popover status.
• A monorepo subdirectory reports the repository, so agents in apps/web and at the root can see each other.
• The boundary is in the database, not in the client. Both the roster and the right to ask are enforced by row-level security in Postgres, so a patched daemon gains nothing.

What leaves your machine

• An ask exports one answer. It is generated on the owner’s machine by a fork with no tools, and a teammate can therefore learn whatever is already in that agent’s context — including the contents of files it read earlier in the session. Same-team, same-repo trust is the boundary, and every ask is logged.
• A fork exports the entire conversation. Every message, every tool result, the contents of every file read into it. Nothing is scanned or redacted, so treat it the way you would treat pasting the transcript into a chat window. popover fork create says so every time.
• A fork is sealed before it is sent, with a key derived from the code itself, so what the server stores is something it cannot read — not the repo, not the title, not the code. The code is the whole credential: anyone holding it can open the conversation, and it can be forwarded.
• Secret paths are denied to a fork — .env, *.pem, .ssh, .aws and the like — in addition to it having no tools at all.
• Your device token never leaves the machine. It is generated locally; the server only ever sees its SHA-256.

Commands

Asking and telling live inside a session, where the agent doing them has the context to write a question worth answering and to do something with the answer. A terminal has neither, so they are slash commands rather than CLI ones.

Limits

• An ask cannot look anything up. It answers from what the session already holds.
• If a teammate’s machine is asleep, their agents show as unreachable and asks fail fast rather than hanging.
• Tells are at-most-once and only ever arrive at a prompt, so a tell is not a way to reach somebody who has stopped typing. The notification to their human is the backstop.
• Rich status — the repo and the file being edited — is shared with everyone in the same repo, with no per-session opt-out.
• Repo scope is a seven-day window on your own activity, so it widens the moment you open an agent in a repo and narrows a week after you stop.
• Revoking a machine stops it refreshing, but a token it already holds stays valid for up to an hour.
• A forked chat is an ordinary session on the recipient’s machine, so it obeys Claude Code’s usual retention like any other.

When something is wrong

popover doctor diagnoses setup problems in root-cause order and is the right first move for almost anything — a missing plugin, a daemon that is not running, a Claude Code too old to report its sessions. popover status says whether this machine is connected and what it is publishing; popover daemon logs is the detail underneath.

A teammate who does not appear on the roster is usually running a version too old to publish a repo identity — the roster counts them and says so. popover update upgrades a machine in place and restarts the daemon on the new build.

To remove it: popover uninstall stops the daemon and unhooks Claude Code, then npm uninstall -g @popoverinstall/cli. Credentials and logs are left behind in ~/.popover/; delete the directory to remove those too.