Questions and sessions
An agent asks you short questions with pinrail ask, and reports what it is doing with pinrail status. Both belong to the agent’s session: one run of the agent, such as a Claude Code conversation. Pinrail shows each session as a thread, with its questions, its reviews and its statuses in the order they happened.
Answering questions
Section titled “Answering questions”Questions wait in the inbox like reviews, marked with a question icon and asks you. Open them and they show in their session’s thread, in the panel beside the inbox or as a page. The questions an agent asks together are one message, numbered 1/3, 2/3 and so on, and are sent back together.
- Pick a choice with a click, or press its number, 1 to 9. A yes-or-no question takes 1 for yes and 2 for no. A star marks the answer the agent recommends. Click a picked choice again to unpick it.
- Pick several where the question says Select all that apply.
- Answer in your own words with Other…, which opens a field under the choices. A question without choices has its field open from the start.
- Add a note to an answer with the button at the right of the question, or press C. The agent receives the note with the answer.
In a field, Enter saves what you wrote and ⇧Enter starts a new line. In the answer to a question without choices, Enter goes on to the next question. A saved note or answer shows under the question, with a pencil to edit it and a bin to delete it when you point at it. Esc leaves a field, so that the keys pick choices again.
The keys answer the current question, which shows its keys on its choices. A key that picks a choice moves on to the next question that has no answer yet. N and P go to the next and the previous question, and a click makes a question the current one.
Sending the answers
Section titled “Sending the answers”The box at the bottom of the thread holds a comment to the agent on all the questions at once. You can dictate it with the microphone in the macOS app.
- Send with Enter in the box, the arrow button, or ⌘Enter from anywhere in the thread. A question you left alone goes back as not answered, and the arrow button’s tooltip says how many there are.
- Decline with the button in the box, or press ⌘D, when the agent should not have asked. The agent is told to stop and is given your reason.
Once you have sent them, the answers show under their questions, with your notes and your comment. The thread stays open, so you can see what the agent does next.
Sessions
Section titled “Sessions”Each session’s thread lists what the agent sent from it, oldest first: its questions, its reviews, which open when you click them, and its statuses. A review the agent revised shows once, where its first round was sent, with its newest round and the round’s number, such as round 2 of 2. Where the agent sent a later round, a Revised line names the review and says when the round waits for you. Click the line to scroll to the review. Where the agent withdrew a review, a line names the review and gives the agent’s reason. The header’s title is the stage of work the agent is on, when it named one, with the agent, the project and the branch under it. The header also shows how many questions and reviews the session holds, and what waits for you. The panel at the right lists what waits on you, and the session’s details: the agent, the session id, the project, the branch, the folder the agent works in and its last activity.
The panel lists the session’s starred reviews under Starred, newest first, and marks a starred review with a star wherever it is listed. It also lists the session’s reviews that have ended, with their outcomes, folded under Reviews until you open it. Click one to open it.
To hide the panel at the right, or show it again, use the button at the right of the header, or press ⌘⇧B. Drag its left edge to resize it. Pinrail remembers both.
A question’s thread links to its session’s page with session and the id in its header. A review sent from a session has a button in its header, on its page and in the side panel, that opens the session’s thread.
On a session’s page, a review you click opens in a side panel beside the thread, in place of the session’s details, and its card in the thread is marked. Deciding or discarding the review closes the panel, and the thread stays where you scrolled. Press Esc or click the close button to close the panel, and drag its edge to resize it. Open as a page opens the review on its own page.
When Opening a review is set to As a page in Settings, a review opens on its own page instead. When you open a review that way from its session’s thread, or from under its session in the sidebar, the breadcrumb at the top reads Sessions ›
The Sessions page, in the sidebar, lists every session that asked you something, sent a review or reported a status: those waiting for you first, then the most recently active. Search for an agent, a session id or a title, and choose a project in the Project menu to list only its sessions. Click a session to open its thread in the side panel, beside the list, as the inbox opens a review. Press J and K to open the next and previous session, and Esc to close the panel. The panel hides the session’s details at first: show them with the button in its header. Open as a page opens the session on its own page. When Opening a review is set to As a page in Settings, sessions open on their own page too.
To archive a session you are done with, click the archive button at the end of its row, or press E on the focused row. You can also archive the open session with the button in its header, or with E. An archived session leaves the Sessions page and the sidebar, but nothing it sent is deleted: its questions and reviews stay in the inbox while they wait, and its thread still opens from a review’s header and from the command palette. Turn on Show archived, beside the Project menu, to list the archived sessions with the others, and unarchive one with its button or E. When an archived session’s agent sends a question, a review or a status, the session comes back by itself.
Sessions in the sidebar
Section titled “Sessions in the sidebar”The sidebar lists every session that is not archived, under its repository, in the Repositories section. Click a repository’s name to see its reviews in the inbox, and click the arrow beside it to collapse or expand it. Click a session to open its thread.
The agent’s icon shows what the session is doing. A pulsing blue dot means the agent reported a status in the last five minutes. A green check means its last status said it had finished. An amber count at the end of the row says how many questions and reviews wait in the session, and they are listed under it, each opening where you answer or decide it. A review that came from no session is listed under its repository. Hover over a session to see its latest status, the agent and the branch.
The button at the right of the section’s heading opens a menu:
- Grouping groups the sessions by repository, by status, by when they were last updated, or not at all. The heading takes the grouping’s name.
- Ordering lists what waits first, then the working, quiet and finished sessions, or the most recently updated first.
- Show details adds a second line under each session. Details chooses what it shows: the last activity, the latest status, the repository, the branch and the agent. The repository is not shown while the sessions are grouped by repository, because each group already names it.
- Show reviews lists what waits under its session, or only counts it.
- Filters list only some agents, repositories or states, or add the archived sessions. Reset clears them.
- Collapse all groups collapses every group, and Expand all groups opens them again.
Pinrail keeps these choices in its settings.
To make the sidebar wider or narrower, drag its right edge, or focus the edge and press ← or →. Double-click the edge to restore the usual width. Pinrail remembers the width on this computer.
What the agent is doing
Section titled “What the agent is doing”An agent that runs pinrail status reports what it is doing, in one line, such as Running the integration tests. Each status shows in the thread at the moment it was sent, between the questions and reviews. Several in a row show as one, the newest, with the earlier ones behind N earlier.
When the agent starts a stage of its work, the thread shows Started with the stage, and the stage becomes the session’s title, in the thread, on the Sessions page and in the sidebar. When the agent says it has finished, the thread shows Finished with what it finished with. An agent that gets more work in the same session starts a new stage, and the session takes its title. The panel at the right lists the session’s stages, oldest first: each with how long it took: until the agent finished it, until the next stage started for one it left unfinished, or until now for the one it works on. Hover over a stage to see when it started. Click a stage to go to where it started in the thread. When a session has more than 8 stages, the panel shows the latest 8. Click N earlier stages above them to show the rest.
The newest status also shows under the session’s id on the Sessions page, and a session the agent finished shows Finished beside its title once nothing waits for you. A status sent after Finished shows the agent working again.
An agent can also send a note: a message in Markdown that tells you something and asks nothing, such as a summary of a stage, a decision it took on its own, or what an investigation found. A note shows in the thread as a message under the agent’s icon, with its headings, lists, tables, links and code. Code in a language the note names, such as rust, is highlighted. A long note is folded: click Show more to read it all.
A note can carry files, such as a chart, a screenshot or a log. An image the note refers to shows in place, and every file is listed at the bottom of the note with its size. Click the save button beside a file, or a link to it in the note, to save a copy where you choose.
A note is information only. It does not wait in the inbox, and it is not the latest status that the Sessions page and the sidebar show. A note after Finished leaves the session finished.
| Keys | Action |
|---|---|
| 1 to 9 | Pick a choice; 1 and 2 answer yes or no |
| N / P | Next / previous question |
| C | Add a note to the answer |
| Enter | Save a note or an answer; send, in the comment box |
| ⇧Enter | A new line |
| Esc | Leave the field |
| ⌘Enter | Send the answers |
| ⌘D | Decline the questions |
| ⌘⇧B | Show or hide the session’s details |