> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plannotator.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up the Plannotator Inbox for Your Coding Agents

> Start the Plannotator Inbox, connect Claude Code, Codex, Pi, OpenCode, or another MCP client, and answer agent questions without holding a session open.

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

<Steps>
  <Step title="Install or update Plannotator">
    Run the installer. It also updates an existing install.

    <Tabs>
      <Tab title="macOS, Linux, or WSL">
        ```bash theme={null}
        curl -fsSL https://plannotator.ai/install.sh | bash
        ```
      </Tab>

      <Tab title="Windows PowerShell">
        ```powershell theme={null}
        irm https://plannotator.ai/install.ps1 | iex
        ```
      </Tab>
    </Tabs>

    See [Install Plannotator](/open-source/start/installation) for other options.
  </Step>

  <Step title="Start the Inbox once">
    ```bash theme={null}
    plannotator inbox
    ```

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

  <Step title="Connect your agent">
    <Tabs>
      <Tab title="Claude Code">
        Use the [Plannotator plugin](/open-source/agents/claude-code) on Claude Code 2.1.287 or later, and [update the plugin](/open-source/agents/claude-code#update) 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.

        <Note>
          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`.
        </Note>
      </Tab>

      <Tab title="Pi and OpenCode">
        Use the [Pi extension](/open-source/agents/pi) or the [OpenCode plugin](/open-source/agents/opencode). Their Inbox tool is off by default. Turn it on with one of these:

        * In the Inbox, open **Settings** and turn the switch on for Pi or OpenCode.
        * Set the environment variable before you start the agent:

          ```bash theme={null}
          export PLANNOTATOR_INBOX_TOOL=1
          ```

        Then start a new Pi session (or run `/reload`), or restart OpenCode.
      </Tab>

      <Tab title="Codex and other MCP clients">
        Add `plannotator inbox mcp` as an MCP server. For Codex:

        ```bash theme={null}
        codex mcp add plannotator-inbox -- plannotator inbox mcp
        ```

        Restart Codex after you add it. The command also adds the server to the Codex app and IDE extension.

        For Cursor, VS Code, Gemini CLI, Zed, and other clients, open the Inbox and use the client picker on its first screen or in **Settings**. It shows the exact command, config snippet, or install link for each client, with the full path to your `plannotator` binary. Apps started from the Dock might not see your shell `PATH`, so prefer that full-path version.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Send yourself a test">
    In a new session, ask your agent:

    ```text theme={null}
    Send me a test message in my Plannotator Inbox.
    ```

    A thread appears in the Inbox. Type a reply and press **Send**.
  </Step>
</Steps>

## 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](#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.

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

Use a plan review or `plannotator annotate` instead when you need a decision before the agent continues.

## Open the Inbox over your tailnet

<Note>
  Requires Plannotator `v0.28.10` or later.
</Note>

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](/open-source/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`:

```json theme={null}
{ "inboxTailscaleAllow": ["you@example.com"] }
```

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

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](https://plannotator.ai/docs/reference/inbox/).

Last verified on October 9, 2026, against Plannotator `v0.28.10`. Maintained by the Plannotator project.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.