Questions, statuses and notes from your agents

An agent is adding a rate limiter to an API gateway. Before it writes the limiter, it needs three decisions from me: how many requests a minute a key should get, whether internal keys should skip the limit, and what a limited request should see. None of them needs a review. Together they need a few seconds of my time, and the answer has to reach the agent without my going to look for its terminal.

Pinrail started as a place to review what agents make: a code change, a plan, a design, a batch of emails, each in a view built for it. Reviews remain the core of it. But working with agents every day, we kept running into three other moments that a review does not fit:

• A short question. The agent needs a choice, a fact or a preference before it can go on. Building a review for it is too much, and asking in the terminal means it waits until I happen to look.
• Not knowing what an agent is doing. A long run is silent until it stops. I cannot tell an agent that is working from one that has been stuck for an hour.
• What the agent found. At the end of a stage, the agent knows things worth keeping: what it measured, what it decided without asking, what it could not do. In a terminal, that scrolls away.

Pinrail 0.5 adds three commands for these, pinrail ask, pinrail status and pinrail status --note, and a place where they all land: the agent’s session. They are still experimental, so they are off until you turn them on in Settings › Labs. This post explains how they work, why we built them this way, and what is still open.

A session is one conversation with an agent, such as one Claude Code conversation or one Codex thread. Agents already have an id for it, and the pinrail command reads it from the environment the agent sets, so the agent does not have to pass it. Everything the agent sends from a session is kept together: its questions, its reviews, its statuses and its notes.

Each session has a thread in the app, oldest first. The Sessions page lists them all, those waiting for you first, and the sidebar lists them under their repositories, with what waits under the session that sent it.

The thread is the point. When I open a question, I see what the agent asked before, what I answered, which reviews it sent, and what it has been doing since. I am not answering a question out of context.

The sidebar lists the sessions under their repositories, and each session’s icon shows its state. A dot means the agent reported something in the last five minutes, and a check means it finished its stage. A number counts what waits for you in the session.

The button beside the sidebar’s heading opens its options. Grouping lists the sessions by repository, by status, by when they were last updated, or in one list. Ordering puts the sessions waiting for you first, or the most recent first. Show details adds a second line to each session, with the details you choose: the last activity, the latest status, the repository, the branch or the agent. Show reviews lists what waits under the session that sent it. The filters list only some agents, repositories or states, or add the archived sessions.

A question is one command. Each question is an argument, followed by its own options:

pinrail ask "CI's rustfmt check fails on cli/src/main.rs. Fix it in a new commit, or amend and force-push?" \
  --choice "New commit" --choice "Amend and force-push" --recommend "Amend and force-push" \
  --context "The commit is already pushed to \`work-items\`, which **nobody else** uses yet." \
  --ask "Run the end-to-end suite before pushing?" --yes-no --recommend yes \
  --ask "Which other checks should run before pushing?" --multiple \
  --choice "CLI tests" --choice "Clippy" --choice "Prettier" --choice "cargo-deny" \
  --ask "Anything else to fold into the commit?"

The questions arrive in the inbox, marked asks you, and open in the session’s thread. A question can offer choices, one or several to pick, ask for yes or no, or take an answer in words. The agent can mark the answer it would choose with a star, and give context in Markdown.

Answering is meant to be fast. The number keys pick a choice and move on to the next question. On a question with several answers, they select and clear choices, and N moves on. A note can go with any answer, so “yes, but” does not need a question of its own. Anything I leave alone goes back as not answered, which the agent must not read as a yes. The box at the bottom takes a comment on all the questions at once, and ⌘D declines them when the agent should not have asked.

The agent waits for the answers, then reads them as plain text:

1. CI's rustfmt check fails on cli/src/main.rs. Fix it in a new commit, or amend and force-push?
Amend and force-push

2. Run the end-to-end suite before pushing?
yes
Note: only the sessions specs

3. Which other checks should run before pushing?
CLI tests
Clippy

4. Anything else to fold into the commit?
Bump the version in the changelog too

We could have built questions as one more plugin, and early on we did. It was the wrong shape. A review is something the person judges: it has a view, a decision and a record. A question is part of a conversation. It needs no payload file and no view, it comes in the middle of a stage of work, and it only makes sense next to what the agent asked before. Putting questions in the session’s thread, not in a view of their own, is what made them feel light.

For questions that depend on each other, or need a long explanation each, a review is still the better tool, and the feedback plugin is built for it.

pinrail status says, in one line, what the agent is doing. It does not wait.

pinrail status --start "Add search to the orders page"
pinrail status "Adding a search index on orders"
pinrail status --done "Opened pull request #88"

--start begins a stage of work and names it. The newest stage is the session’s title in the thread, in the sidebar and on the Sessions page, so a session is called Add search to the orders page, not by an id. --done says the stage is finished, and the sidebar marks the session with a check.

Each status also answers the agent. It prints the stage Pinrail last recorded for the session:

$ pinrail status "Adding a search index on orders"
Current stage: Add search to the orders page (started 2026-11-10 09:41)

That small line turned out to matter. An agent loses track of its stages, especially after its context is compacted, and the line tells it what Pinrail thinks it is doing. After --done, it says that no stage is open, which reminds the agent to start one before new work.

A note is a status that carries a message: Markdown of up to 10,000 characters, with up to ten files. It asks nothing and never waits in the inbox.

pinrail status --note --file summary.md --attach latency.png --attach run.log

An agent uses a note at the end of a stage, for a decision it took without asking, or for what an investigation found. An image the note refers to shows in place, and every file is listed under the note to save. It is the part of the agent’s work that would otherwise scroll away with the terminal.

None of this works unless agents use the commands at the right moments. Pinrail installs a skill into each agent it finds, in Settings › Agents, which tells the agent when to ask, when to start a stage, and when to send a note. When sessions are off, the skill leaves those parts out, and the app refuses the commands, so an agent never sends something you cannot see.

The skill does a lot of the work, and it is also the weak point, as the next section explains.

We are putting this in Labs, not in the main app, because three things are not settled.

Reaching an agent that is waiting for you. An agent reads what Pinrail has for it when it runs a command. An agent that has finished its turn and is waiting for you runs none, so anything sent to it waits too. Every agent handles this differently, and we want to find the best way for it to work across all of them. That is coming in a future release.

Knowing whether a session is still running. Pinrail only knows what an agent last reported. It cannot yet tell an agent that is thinking from one that has stopped, which matters before we let you resume a stopped session from the app. We are working on it.

Agents forgetting to report. A model that is deep in a task forgets to start a stage, or reports too much. The current stage line helps, but it will never be perfect, so the app has to stay useful when the reports are sparse.

Sessions, questions, statuses and notes are in Pinrail 0.5. To turn them on:

Then give an agent a task long enough to have stages. We would like to hear how it goes, especially where it breaks: use Send feedback in the app, or open an issue on GitHub.