Skip to content

Sessions

A session is one run of an agent, such as a Claude Code conversation or a Codex session. Everything the agent sends you from that run belongs to it, and Pinrail shows it as one thread, in the order it happened. A session lets you see what an agent is doing and answer it without leaving the context of its work.

The pinrail command reads the agent and its session from the agent’s environment, such as CLAUDE_CODE_SESSION_ID for Claude Code, and sends them with each review, question and status. The agent does nothing to name its session. A review or a question sent from no agent, such as from a CI job, belongs to no session and shows only in the inbox.

WhatSent withWaits for youWhat the agent gets back
Questionspinrail askYes, in the inboxYour answers, your notes and your comment
Reviewspinrail submitYes, in the inboxYour decision, as the plugin defines it
Statusespinrail statusNoNothing
Notespinrail status --noteNoNothing

Questions and reviews ask for your answer: the agent waits until you give it. Statuses and notes only tell you something.

A question is a short request for an answer the agent needs before it can go on, such as a choice, a fact or a preference. Under the hood, a set of questions is a review of its own kind: it waits in the inbox, ends in the same ways, and the command that asked it exits with the same codes. It needs no plugin, and you answer it in the session’s thread rather than in a plugin’s view.

The questions an agent asks together are one set, and you send their answers together. You can answer in your own words, add a note to any answer, and add a comment on the whole set. A question you leave alone goes back as not answered, which is not a decision. Declining the set tells the agent to stop, as discarding a review does.

A status is one line that says what the agent is doing, such as Running the integration tests. It shows in the thread at the moment it was sent, and the newest status shows on the Sessions page and in the sidebar.

An agent groups its work into stages. It starts a stage with pinrail status --start, which names it, and the stage becomes the session’s title. It ends the stage with pinrail status --done once the work is approved and delivered, or when nothing needs a review. A session can have several stages, one after the other.

A note is a message in Markdown that tells you something and asks nothing, such as a summary of a stage, a decision the agent took on its own, or what an investigation found. It can carry files, such as a chart or a log, and shows images in place.

A session can hold work items. While it holds them, the reviews and questions it sends belong to them, and its thread shows the changes it makes to items and its comments on them. A comment you add to an item the session holds reaches the agent the next time it runs pinrail status.

A session appears with the first thing its agent sends, and stays on the Sessions page and in the sidebar until you archive it. Archiving deletes nothing: the session leaves the lists, and its questions and reviews stay in the inbox while they wait. A session whose agent sends something again comes back by itself.

When you set Keep reviews for in Settings › Data, Pinrail deletes old reviews from the history, and with them each session that has no review left and no activity in that time. Deleting a session releases the work items it held.