Skip to main content
The Plannotator Inbox is one local window on your computer where agents leave you messages, questions, files, and guided reviews. You answer when you can. No agent waits on the Inbox, so a session keeps working or ends its turn after it writes. When you press Send, your reply goes back to the session that asked.

​
Prerequisites

  • A coding agent: Claude Code, Codex, Pi, OpenCode, or another MCP client.
  • Plannotator on the same computer. Run plannotator --version and verify v0.28.9 or later.

​
Set up the Inbox

1

Install or update Plannotator

Run the installer. It also updates an existing install.
See Install Plannotator for other options.
2

Start the Inbox once

The Inbox starts and opens in your browser. Run it once before you connect an agent: the first run writes the file that the Claude Code, Pi, and OpenCode connections look for when a session starts.After that, you do not need to keep the Inbox running. An agent that writes to a stopped Inbox starts it in the background, without opening a tab.
3

Connect your agent

Use the Plannotator plugin on Claude Code 2.1.287 or later, and update the plugin if you installed it earlier. Its Plannotator mod adds a plannotator_inbox tool, which is on by default.Quit and restart Claude Code. Claude Code adds the tool when it starts, so a session that started before your first plannotator inbox does not have it. A new conversation inside a running Claude Code is not enough.
The mod does not run in claude -p, SDK runs, or on Windows. There, connect Claude Code through MCP like Codex: claude mcp add --scope user plannotator-inbox -- plannotator inbox mcp.
4

Send yourself a test

In a new session, ask your agent:
A thread appears in the Inbox. Type a reply and press Send.

​
How it works

  • Threads by project. Each agent session writes to its own thread unless the agent names a thread to join. The sidebar groups threads by project: the repository, or the folder when there is no repository.
  • Questions and Send. Questions appear as cards. Click to pick an answer. Your picks save at once, and Send delivers your picks, your words, and any file annotations as one reply.
  • Replies wake the session. With Claude Code, Pi, or OpenCode 2, your reply arrives in the session that asked as a new turn once the session is idle. It never interrupts a running turn. Codex and other MCP clients are not woken: the agent reads your reply with the wait_for_reply or read_thread tool.
  • Local by default. The Inbox binds 127.0.0.1 and stores everything under ~/.plannotator/inbox/ (or $PLANNOTATOR_DATA_DIR/inbox/). To open it from your other devices, see Open the Inbox over your tailnet.

​
How to use it

  • Hand off long work and let the agent leave its questions in the Inbox instead of stopping to wait for you.
  • Get decisions while you are away from the terminal, then answer several threads in one pass.
  • Review files the agent attached, and annotate them before you reply.
  • Read guided reviews of a code change, section by section.
At first, ask your agent to use the Inbox by name, for example “leave your open questions in my Plannotator Inbox”. With an MCP-only agent, also tell it to wait for your reply.
Use a plan review or plannotator annotate instead when you need a decision before the agent continues.

​
Open the Inbox over your tailnet

Requires Plannotator v0.28.10 or later.
If you use Tailscale, you can open the Inbox from your phone, tablet, or another computer on your tailnet. See Review Plannotator sessions over Tailscale for Tailscale setup and HTTPS certificates. Turn it on in one of two ways:
  • Run plannotator inbox --tailscale. It publishes until the Inbox stops and works with --background and --no-open. If the Inbox is already running, the command asks it to publish.
  • In the Inbox, open Settings and turn on Over your tailnet. The switch stays on, so the Inbox publishes at every start, also when an agent starts it. You can turn it on only from this computer.
On the other device, open the address that the command prints and Settings shows: https://<machine>.<tailnet>.ts.net:<port>/, where the port is the Inbox’s own port.
  • Tailnet only. The Inbox stays bound to 127.0.0.1. Tailscale Serve publishes it over HTTPS inside your tailnet. The Inbox never uses Tailscale Funnel.
  • Only your login. The Inbox lets in only the Tailscale login that owns this computer. It refuses other logins and tagged devices.
  • Agents stay local. MCP and the reply wake answer only on this computer, never over the tailnet.
  • Tailscale unavailable. If Tailscale is missing or signed out, the Inbox still runs on this computer, and Settings shows why it could not publish.
  • Hard off. PLANNOTATOR_INBOX_TAILSCALE=0 keeps it off, even with --tailscale or the switch.
To let in another login, for example your own login on a shared tailnet, add it to ~/.plannotator/config.json:
An allowed login can reply and send New messages. Both run as turns in your agent sessions on this computer, where agents run commands. Allow only people you would let run your agents. Anyone who holds your unlocked phone while it is signed in to Tailscale has the same access.
To stop publishing, turn the switch off or quit the Inbox. The Inbox removes the address when it stops or restarts. After a hard kill or a reboot, the address stays in Tailscale until the Inbox starts again. To remove it sooner, run tailscale serve --https=<port> off. To keep a published Inbox running after you close the terminal, start it with plannotator inbox --background --tailscale. If you followed the earlier manual workaround, remove that mapping with tailscale serve --https=443 off. It exposes the whole Inbox, including its agent tools, to everyone on your tailnet. The Inbox detects it, refuses requests through it, and Settings offers to replace it with the owner-only address.

​
Troubleshooting

  • My agent does not see the Inbox tool. Run plannotator inbox once, then fully restart Claude Code or OpenCode, or start a new Pi session. On Pi and OpenCode, also turn the tool on. When PLANNOTATOR_INBOX_TOOL is set, it decides for every agent and overrides Settings.
  • Codex does not write to the Inbox. Codex has no built-in Inbox tool. Add the MCP server with codex mcp add plannotator-inbox -- plannotator inbox mcp, then restart Codex.
  • My reply did not arrive. A reply waits until the session is idle. MCP-only agents must read it with wait_for_reply or read_thread, so ask the agent to check.
  • I cannot open the Inbox from my phone. Sign in to Tailscale with the same login on both devices, check that Tailscale is signed in on this computer, and check that Over your tailnet is on in Settings.
  • The Inbox address changed. When its last port is taken, the Inbox starts on a new port and shows a notice. MCP connections through plannotator inbox mcp follow the change. Allow browser notifications again at the new address.
  • I want to stop the Inbox. Press Ctrl+C in the terminal that runs it. For a background Inbox, find its process ID with grep '"pid"' ~/.plannotator/inbox/inbox.json and run kill <pid>. The next agent that writes starts it again.
For every command, setting, MCP tool, and file on disk, see the Inbox reference. Last verified on October 9, 2026, against Plannotator v0.28.10. Maintained by the Plannotator project.
Last modified on October 10, 2026