Terminal scroll is not a workflow

Chat interfaces are built for conversation, not for maintaining action items, decisions, and artifacts that need your attention. When you’re running one agent, the cognitive overhead is manageable. When you’re running two or three sessions across different tools and repositories, unless something routes these items to somewhere static and responsive, it’s easy to get lost.

That’s why I built an agent inbox and aptly named it Agent Inbox.

Where Agent Inbox is useful

Claude Code ships an Agent View that surfaces blocked status and pending decisions for Claude Code sessions. The limitations are largely around managing sessions from other tools and the ability to easily find previous decisions and why context drove me to make them.

If you’re also running Copilot CLI, or an agent built on a different SDK, those sessions don’t appear in Agent View. Agent Inbox sits alongside Agent View and maintains a cross-project queue. Any configured agent can flag an item or update a board in it, regardless of which SDK or CLI produced the session.

The architecture

Agent Inbox adds no AI. It’s infrastructure built around the AI that’s already running on your machine.

The core is a stdio MCP server that runs locally. Agents connect to it the way they connect to any other MCP tool server, by calling tools like flag and status with a structured payload. The server reads from stdin and writes to stdout. It makes no network calls of its own. An agent running in a sandboxed environment with restricted outbound access can still flag an item without friction.

Every flagged item and board row lands in a single database at ~/.agent-inbox/inbox.db, in WAL mode and the database is shared across every agent session on the machine, which is how the cross-project view works as every agent writes to the same local file.

What a coding agent inbox should capture

The tool agents actually call is flag, and it takes three kinds: question, note, and done.

A question is blocking. It creates a row marked as waiting, surfaced with direct response choices so you can answer from the inbox without switching to a terminal. The agent polls pending, picks up the response, and calls resolve once it has acted on it.

note is the catch-all for everything non-blocking - an assumption the agent made, a workaround it took and wants on record, tech debt it noticed, etc.

For a multi-item effort, a rollout checklist, a review queue, a migration’s file list, the same agent keeps one titled tracking board alive with board_upsert, board_row, and board_advance, so the human watches standing status instead of a scroll of individual flags.

Live presence works the same way. The agent calls status at real phase changes, starting a task, spawning subagents, wrapping up, and the viewer shows it live. A glance at the inbox tells you whether an agent is still running without going back to a terminal.

How agents interact

Agent reporting to the inbox lives in the agent’s system prompt, the same fragile place I’ve relied on before for behavioral rules and learned to distrust. It gives the agent a taxonomy of when each flag kind is appropriate, with concrete examples. A question is warranted when the agent cannot proceed without a decision that changes the scope or direction of the task. Everything else non-blocking becomes a note. The agent exercises judgment about what’s worth logging and the contract gives it the parameters to reason within.

Getting this right took more iteration than any other part of the project. An early version of the prompt produced too many questions. Models are well-trained to ask before acting and they’ll surface things that genuinely don’t require a human in the loop — whether to create a helper function or inline the logic, for example. Tightening the definition of when a question is warranted, and being explicit that note exists for everything that doesn’t require a decision, changed the behavior significantly.

The contract is still evolving. If you’re building something in this space, plan to spend as much time on the prompt that teaches the agent what to file as on the infrastructure that stores it.

---

The project is at github.com/shariqh/agent-inbox. If you’re running more than one coding agent and losing decisions to terminal scroll, the code is there to inspect or adapt.