Inbox

I have ADHD. Working with an agent in a chat thread format is very cognitively taxing. The number of things you're having to hold in your head begins to compound the longer the session goes on. The questions, bugs, ideas, and tasks all begin to pile up and intermix making it difficult to keep everything in line.

Inbox provides immediately apparent relief here by giving your agent an organized, stable place to surface everything that needs a decision. Inbox also makes sure your agent always provides a proactive, anticipatory set of quick actions on each item, including a recommended action.

Even better, Inbox provides your agent a place to surface latent issues and opportunities, ones that it might otherwise gloss over in the interest of exclusively addressing the task at hand.

Inbox is available for Claude Code in the terminal and desktop app, and Codex in the ChatGPT desktop app. Each variant is uniquely crafted for each platform, but works in same fundamental way in all three.

If you're like me, just paste a link to this Github repo to your agent and ask it to install.

If you want to do things the old way, proceed...

In a Claude Code session in the terminal, type:

/plugin install inbox --marketplace petekp/inbox

Answer y to add the marketplace, then choose a scope. It starts working in that session. A user-scope install also covers Code sessions in the Claude desktop app on this machine.

To install from the Claude desktop app instead, open a Code session:

1. Click + beside the prompt, then Add plugins.
2. In the Directory, click + at the top right, then Add from a repository.
3. Enter petekp/inbox and click Sync.
4. Click + on Inbox.

This installs it for your user account, so it works in the terminal too. /plugin does not run in the desktop app, and the inbox does not reach the app's cloud sessions.

If your organization manages Claude Code, an inbox you install yourself works only in part. Claude Code skips the hooks it uses to add to what Claude reads, so Claude gets neither the inbox's instructions nor its list of what waits on you. The inbox also keeps the old conversation's list after /clear or a resume, and shows no permission prompts or failed turns. Questions, tasks and findings still reach it. To get everything, ask an admin to list the inbox in your organization's managed settings.

To update, run these, then /reload-plugins in any session that's already open:

claude plugin marketplace update inbox
claude plugin update inbox

• It makes one Sonnet call after each of Claude's replies. See Cost.
• It was built and tested with Claude Code 2.1.300.

codex plugin marketplace add petekp/inbox
codex plugin add inbox@inbox

Then, in the ChatGPT desktop app, trust the plugin's hooks: click the hook icon beside the prompt's approval setting, then Allow all. Codex runs a plugin's hooks only after you trust them. To open the inbox, press + at the top right of the window, then choose More tools, then Inbox.

codex/README.md covers updating and running the codex command from inside the app.

The PRs tab needs the GitHub CLI, gh, signed in.

Type /inbox in Claude Code, or open the Inbox tab in the ChatGPT app. The inbox has three tabs.

Questions the agent asked you, and tasks only you can do.

The agent doesn't have to do anything special to put a question here. After each reply, a model reads what the agent wrote and records each question in it, with its possible answers. The agent's recommended answer comes first. Press an answer and it goes to the agent as your message. You can also type your own reply, or press Explain to have the agent say more before you decide.

A task is something like signing in or adding an API key. It comes with buttons for its steps, such as copying a command or opening a file. In Claude Code, running the command with ! closes the task once it succeeds.

Bugs, risks and ideas the agent noticed outside the task it's working on. The agent records them and carries on with its task, and you decide later which ones to act on. Fix on an issue, or Do it on an idea, hands it to the agent. File issue has the agent file it in your issue tracker, such as Linear or GitHub, or link the issue that already covers it. Reply sends your own words about it. Explain has the agent say why it matters and what fixing it would involve, without acting. Discuss talks it through, and Dismiss drops it.

Pull requests from this session and your current branch. Each one is marked Blocked, Ready or Waiting, and lists what blocks it: review comments waiting on you, failing checks and merge conflicts. Buttons hand the work to the agent: address one review comment or all of them, draft a reply, fix a failing check, resolve conflicts, or merge.

When you answer a question in your own message, a task gets done, or the agent fixes a finding, the inbox closes the item. Closed items fold away under the open ones, each with how it ended.

The agent reads the inbox too. Beside each of your prompts, it sees what's still open and what you answered, even after the conversation is compacted.

Every press shows what it did right away. Discuss reads "Discussing…" until the agent replies, then "✓ Discussed".

• Terminal: each action shows the letter that runs it. 1, 2 and 3 switch tabs, and j and k move up and down. ctrl+x tab moves focus from the prompt to the line above it, then to the panel, then back to the prompt.
• Claude desktop app: you click. Type /inbox to open the pane.
• ChatGPT app: you click, or press the same keys as in the terminal. The tab shows no letters.

In Claude Code, a line above your prompt counts what needs you and the findings waiting, with a button that opens the panel. When Claude stops on an error, a second line says why, with a Resume button after an API error. The ChatGPT app has no such line. Inside the Herdr terminal, the counts also show in its sidebar.

To see every part with sample items in Claude Code, run /inbox demo. Presses on them change only the samples and send nothing. Press Hide demo, or run the command again, to go back to your own items. /inbox demo recording shows the same samples without the notices that mark them, for recording a video. Run /inbox demo to end it.

In Claude Code, the inbox adds two things:

In one long Opus session, this came to about 1% of the total cost. A shorter or cheaper session pays a larger share. On a Claude plan, these count toward your usage limits.

In Codex, the update after each reply runs through the codex binary inside the desktop app, with your Codex sign-in. It uses about 16,000 input tokens per reply, most of them the base instructions every codex exec call includes. It counts toward your plan's usage.

This covers the Claude Code mod. codex/README.md covers the Codex plugin.

What leaves your machine. Three things, and nothing else:

• After each of Claude's replies, the inbox sends one Sonnet request to Anthropic through Claude Code's own model connection. It holds your last prompt, Claude's reply, the inbox's open items, and a line for each tool Claude ran. A tool line reads like ran: npm test or edited src/app.ts. Cost gives the request's size.
• When the inbox may have missed a turn, it asks the same model to update it from the whole conversation. It forks the conversation for this, or reads the transcript after a resume.
• To fill the PRs tab, it runs read-only gh queries: gh pr view, and gh api graphql for review threads. They reach GitHub under your own gh sign-in. The inbox never reads your GitHub token.

Programs it starts.

Messages it sends as you. When you press an answer or action button, the inbox sends Claude a message in your name. The message is the answer you chose, or a request about the item, such as asking Claude to fix a finding. Resume, on a stopped turn, sends Continue. Every message it sends starts from a press. When you mark a task Done that Claude is waiting on, the inbox tells Claude a few seconds later, or once Claude's running turn ends.

What it adds to Claude's context.

• Its instructions, about 1,350 tokens, in every request.
• A note beside your prompt when you answer one of Claude's numbered questions, or when the inbox changed since Claude last saw it.
• Its open items after the conversation is compacted, so Claude keeps them.

What its hooks see.

• Tool calls. The inbox reads each call to write the tool lines above, to show a question while Claude's question dialog is open, and to find a PR this session opens with gh pr create. It passes every call on unchanged, except calls to its own two tools. record saves a question, a task or a finding and close closes an item. The inbox answers these itself, so they run without a permission prompt.
• Permission prompts. While Claude Code asks you to approve a tool call, the inbox shows a row for it, then passes the request on unchanged. It never approves or denies a permission prompt.
• Tool descriptions. It lists its own two tools to Claude up front, instead of behind tool search. It leaves other tools' descriptions alone.
• Shell commands you run with !, and their output. A command that runs with nothing on stderr closes a task that asked you to run it.
• Session starts. After /clear, a resume or a fork, the inbox loads that conversation's items. It passes the event on unchanged.
• Your theme setting, to match its colors.

What it keeps. The inbox saves each session's items, and the PRs it tracks, in Claude Code's plugin storage on this machine. It keeps the 40 most recent sessions and deletes older ones. An item can summarize part of the conversation, so it may name the people in it. Nothing goes to the plugin's author.

It also adds the /inbox command.

Read AGENTS.md first. docs/looks.md says which file owns each rule and where the three apps differ on purpose.

Run the mod from a clone:

claude --plugin-dir /path/to/inbox

The session reloads the mod when you change one of its files.

The Codex plugin shares the rules in hooks/ with the mod. Rebuild its bundles after changing either:

npm --prefix codex ci         # once
npm --prefix codex run build

codex/README.md covers trying a build in Codex.

./scripts/check.sh runs Prettier, claude plugin validate, a type check and the tests, and checks the Codex bundles are current. The type check needs the types Claude Code writes to .claude-plugin/types/ the first time it loads the mod.