Sessions

list_sessions

Read-only. Allowed without asking.

Agent sessions, newest first. Each line shows the session id, the task, the agent and where it runs, the state, the time and the session's note. For an agent's hand-back, the note is the report's summary; the line also says handed back partial or handed back blocked when the report does, and ends with counts from the report: the Done when items met and not answered, the images and the questions. A session whose agent reported what it used ends with it, such as used 262k tokens · 1 min working. See What it used.

Session 3f2a9c1b · DEV-21 MCP server skeleton · Claude Code in a terminal on DESKTOP-1 · finished, waiting for the user's review · 2026-09-24 13:53:07 · MCP endpoint added at /api/mcp. Tests pass. (2 of 3 Done when items met · 1 question)
Session 9c0d1e2f · DEV-22 Start sessions from the app · Claude Code in a terminal on DESKTOP-1 · finished, waiting for the user's review · 2026-09-25 10:12:40 · handed back partial · The terminal opens in the project folder; the task doesn't show the running session yet. (1 of 3 Done when items met · 1 not answered)

The states read: starting, running, finished, waiting for the user's review, reviewed and done, closed and failed.

start_session

Starts an agent on one of the user's computers or in its cloud. Agents ask the user first.

Asks to start Claude Code or Codex working on a task, in the task's folder, the same way as Start with Claude Code in the app: where the task runs, unless where says otherwise. See Start, resume and close sessions. Nothing starts without the user's say: on this computer they allow it in PacedMind, and another computer does what its own settings say.

Refused when the task is the user's own (DEV-22 is marked as the user's own task (human), so it never gets an agent session. Ask the user before changing that with update_task.) or already has a running session (DEV-22 already has a running session.).

On this computer

On the desktop app's server, the session goes to this computer unless computer names another one or the task runs on another computer (its Computer, or its project's). The request waits in PacedMind's window: a card, Start a session on this computer?, with the task, the agent and where it runs, and the folder, with Refuse and Allow, and a notification such as Start DEV-22 with Claude Code · Terminal?. Nothing starts until the user allows it, within 10 minutes. The tool returns:

Asked the user to allow DEV-22 with Claude Code (terminal): PacedMind shows the request in its window and a notification. It starts once they allow it (within 10 minutes). Tell the user to look at PacedMind; don't ask again.

For the cloud it adds Cloud sessions can't report back to PacedMind; the user marks the task finished or done. A task that can't run on this computer at all is refused: DEV-22 can't run on this computer. Once the user allows it, the start can still fail, for example when the computer lacks the agent's tool or app, or the folder can't be used; PacedMind's message says why. See Start a session.

On another computer

With an account, the request goes to another of the user's computers: the one computer names, or the one the task runs on. On PacedMind Cloud's server, every request goes to a computer: the one computer names, else the task's, else its project's, else, for a task with Needs, one whose agent has them, else the account's default one.

The request is marked as an agent's, and asks for a new session only. An agent never counts as having a two-factor code, so only a computer whose Two-factor code setting is off takes it. What that computer's settings do:

The tool waits a few seconds for the computer's answer. When the computer hasn't answered yet and would start the session: Sent to Studio Mac, which starts Claude Code on DEV-22 as soon as it sees the request, followed by ; it hasn't been online in the last few minutes, and the request waits there for 10 minutes when it's offline. When the computer refused it or couldn't start it: Studio Mac didn't start Claude Code on DEV-22: and the reason.

A task that belongs to one computer goes only there: DEV-22 runs on DESKTOP-1 only. Ask that one, or the user picks another computer in its details. A session that a computer starts this way, without asking, says so in its history: …: an agent's request from elsewhere, as this computer allows. See When an agent asks.

close_session

Deletes. Agents ask the user first.

Marks a running session as closed, for example when its terminal was closed or it got stuck. The task goes back to Todo if it was in progress.

request_changes

Reopens an agent's session in a new terminal on the user's computer, once the user allows it. Agents ask the user first.

Asks to send work an agent handed back to it again, with what the user wants changed, the same way as Request changes under a report in the app. See Request changes.

The tool only asks. PacedMind shows the request in its window, with Allow and Refuse, and as a notification (Send DEV-22 back to Claude Code with changes?). Nothing happens until the user allows it, within 10 minutes. The tool returns:

Asked the user to allow sending the changes to Claude Code for DEV-22: PacedMind shows the request in its window and a notification. Once they allow it (within 10 minutes), session 3f2a9c1b reopens in a new terminal and the task is in progress again. Tell the user to look at PacedMind; don't ask again.

The task's latest session must have handed the task back: it's Finished, or Done when the user already marked the task done. Once the user allows the request, PacedMind:

1. adds the changes to the agent's last report;
2. reopens the session in a new terminal, in the task's folder, in a new conversation whose first message sends the agent to start_task, which shows the changes first;
3. sets the session back to Running (You asked for changes: …) and the task to In progress, also when the task was done.

Claude Code and Codex both start a new conversation, with the changes and the last report from start_task. Claude Code doesn't resume its earlier conversation, so that PacedMind's tools are connected when it reads its first message. The new conversation has its own id, so closing a terminal still open on the old one doesn't close the reopened session. The first message reads:

Task title: Start sessions from the app. Use the task title as the session name. PacedMind task DEV-22, session 3f2a9c1b: the user reviewed your work and wrote back. Call the pacedmind MCP tool start_task with task DEV-22 and session 3f2a9c1b to read it, then follow the instructions it returns.

Answers to the agent's questions, sent with Answer its questions in the app, go back the same way. See Answer the agent's questions.

Only a session in a terminal on this computer can be reopened. Refused, before anything is asked, when:

• the task's latest session hasn't handed it back, or the task has no session (DEV-22 has no hand-back to send changes to: its latest session is running. start_session starts a new session.);
• changes is empty (Write what should change.);
• the task is the user's own (DEV-22 is marked as yours. Hand it to Claude Code or Codex first.);
• the task already has a running session (This task already has a running session);
• the task's latest report comes from another of its sessions (DEV-22 has a newer report. Ask for the changes on that one.);
• the session runs in a desktop app or in the cloud (This session runs in the Claude app. Open it there and write your changes to the agent.);
• the session ran on another computer (This session ran on another computer. Ask for the changes in PacedMind there.).

After the user allows it, the task's folder can still be unusable (Can't use the folder …), or the terminal can fail to open: the message in PacedMind says why, and the session stays as it was.

On PacedMind Cloud's server, request_changes sends nothing: it returns a link to the task, where the user sends the changes with Request changes and their two-factor code, or does it in the desktop app (Sending changes reopens the agent's session on the computer it ran on, so the user sends them themselves: …).

The protocol for agents working on a task

A session that PacedMind starts begins with a message naming the task and the session. The agent picks the task up with start_task. While it works, it can attach screenshots with attach_image, keep the user posted with report_progress, and ask a question it needs answered with ask_user. It hands the task back with a report through finish_task. The pacedmind-agent-session skill teaches the protocol in detail. See How a session runs.

An agent connected to PacedMind Cloud's server, such as a session in the Claude or Codex app, follows the same protocol without attach_image and ask_user: that server can't read files from the agent's computer, and questions that wait for an answer come from the computer a session runs on. It asks in its conversation instead, and finish_task takes no images there.

get_next_task

Read-only. Allowed without asking.

The next task in a project that is ready to be worked on: the first task in roadmap order that is to do or in the backlog and whose dependencies are all finished, each task it waits for done or in review. A task that an agent handed back partly done or blocked counts as finished only once it's marked done or handed back again as done, or a newer session of it is marked finished. Returns the same details as get_task, or Nothing in … is ready right now.

start_task

Changes data. Allowed without asking.

Tells PacedMind that the agent is starting work on a task. The session becomes Running (Claude Code read the task over MCP) and the task In progress.

With environment, PacedMind records Claude Code says it runs as …, with the MCP servers github, linear, or … with no other MCP servers, before Claude Code read the task over MCP. It keeps up to 30 plain server names: pacedmind, its earlier name organizer, and names with spaces or other unusual characters are left out, and it lists claude.ai connectors (claude_ai_…) and plugins' servers (plugin_…) apart. Sessions shows it as Agent says.

For a Claude Code session PacedMind started in a terminal, the servers come from Claude Code's own record of the session instead of mcp_servers, with the ones that failed, wait for sign-in or are still connecting (Not available to Claude Code: …). It's recorded even when the agent leaves out environment. See What a session actually has.

Returns, in this order:

1. what the user wrote back, when they reviewed the last hand-back and sent it back: the changes they asked for with Request changes or request_changes, with the instruction to make these changes first, or their answers to the agent's questions, with the instruction to go on with the task using them;
2. the task's details, the same as get_task returns, including the numbered Done when items and the last report, if the task was handed back before;
3. the session id, when to keep the user posted with report_progress and to ask with ask_user, and the instructions for handing the task back with a report.

For example:

PacedMind session: 3f2a9c1b
Work on this task here. Keep the user posted with report_progress, but only when it matters: your plan once you have one (send it again as steps get done) and anything that changes the scope or the risk (kind issue). Skip routine updates. When you need the user to decide something before you can go on, ask with ask_user: it waits for their answer, which they can give on any device.
When it is ready for the user to check, call finish_task with task DEV-22, session 3f2a9c1b and a report:
- summary: one or two sentences on what changed and what the user should look at first;
- criteria: your answer to each Done when item above (met, partly or not_met, with a short note on how you checked);
- images: screenshots of anything you changed that can be seen. Save each as a PNG, JPEG, GIF or WebP file and pass its path; attach_image adds them while you work;
- verify: steps the user can follow to check the result, and questions: anything the user has to decide;
- details: anything longer, in Markdown.
If you can't finish, still call finish_task, with outcome partial or blocked, and say why. Do not mark the task done yourself.

The criteria line appears only when the task has Done when items.

When the user asked for changes, the result starts with them:

The user reviewed your last hand-back and asked for changes (2026-09-25 11:02:13):
Show the running session in the task list too, not only in the task panel.

Make these changes first; your last report is at the end of the task below. Then hand the task back again with finish_task and a new report whose summary starts with what you changed.

When the user answered the agent's questions, the result starts with the answers instead:

The user reviewed your last hand-back and answered your questions (2026-09-25 11:02:13):
My answers to your questions:

1. Should the task list show the running session too?
Yes, next to the title.

Go on with the task using these answers; your last report is at the end of the task below. Then hand the task back again with finish_task and a new report whose summary starts with what you changed.

The changes or answers stay on the last report until the agent hands the task back with a new one, so every start_task until then shows them.

With a session id of that task, start_task sets that session back to Running, whatever its state. Without one, it uses the task's running session; when there's none, as when the agent was started outside PacedMind, it creates one (Started outside PacedMind). It refuses to create one for tasks that are the user's own.

attach_image

Changes data. Allowed without asking.

Adds a screenshot or another image to the task the agent works on, so the user sees it with the agent's report. The agent saves the image as a file first and passes its path; PacedMind keeps its own copy, in the attachments folder next to its database. finish_task takes images too.

PacedMind tells the type from the file's contents, not from its name. The path can be absolute, start with ~ for the home folder, or be a file:// URL. On Windows, Git Bash paths such as /c/Users/…, WSL paths such as /mnt/c/Users/…, and /tmp/…, which stands for the system's temp folder, work too. A relative path is read from the session's folder, or the project's when the session has none.

The image goes to the session named in session, else the task's running session, else its latest session. While the session runs, the image waits and becomes part of the report at finish_task; after the task was handed back, it joins that session's last report.

Returns the caption in quotes, or an image, then the size in pixels when PacedMind can read it, the type and the file size:

Attached "Task panel with the running session", 1440×900 PNG, 212 KB to DEV-22. It will be part of your report when you call finish_task.
Attached an image, 1280×800 JPEG, 1.4 MB to DEV-22, in your last report.

Refused when:

• the task has no session yet (DEV-22 has no session yet. Call start_task with task DEV-22 first.);
• the session already has 40 images (This session already has 40 images. Attach the ones that show the result best.);
• the path is empty (The image path is empty.);
• there's no file at the path (PacedMind can't find …. Save the image to a file and pass its absolute path.). A path that PacedMind completed or translated, such as a relative or a Git Bash path, is shown with the one it read: … (read as …);
• the path is a folder (… is a folder, not an image file.);
• the file is larger than 20 MB (panel.png is 23.4 MB; an image can be up to 20 MB. Save a smaller one, for example only the window instead of the whole screen.);
• the file isn't one of the four image types (panel.png isn't a PNG, JPEG, GIF or WebP image.).

report_progress

Changes data. Allowed without asking.

Keeps the user posted while the agent works on a task, when it matters: its plan once it has one, a problem that changes the scope or the risk, or a decision it needs from the user. It isn't meant for routine steps, and it doesn't hand anything back: finish_task does. To wait for the user's answer in PacedMind, the agent asks with ask_user instead.

Each call needs a message, a plan, or both. The update goes to the session named in session, else the task's running session; a session PacedMind started can only report on its own. PacedMind records it in the session's history:

With both, the plan is recorded first, so a question stays the latest word from the agent.

Returns Your plan is on DEV-22: 2 of 5 steps done. for a plan, and for a message Noted on DEV-22., or for a question PacedMind shows your question on the task and notifies the user. Ask it in this conversation too, then wait for the answer here. With both, the two sentences follow each other.

Refused when:

• the task has no running session to report on (DEV-22 has no running session. Call start_task with task DEV-22 first.);
• a session PacedMind started names another task or session (This session works on DEV-21 (session 3f2a9c1b); it can only report on that task.);
• there's neither a message nor a plan (Pass a message, a plan, or both.);
• the session already sent 100 updates (This session already sent 100 updates. Put the rest in your report when you call finish_task.).

ask_user

Changes data. Allowed without asking.

Asks the user a question the agent needs answered before it can go on, and waits for the answer. PacedMind shows the question under the session's state line in the task's details and in Sessions, with a field for the answer, and the desktop app notifies (DEV-22 has a question for you). The user answers in PacedMind. See Answer while it works.

PacedMind records Claude Code asks you: and the question, and the session waits for you as it does for a question sent with report_progress. The question stays open for 30 minutes, but a call waits only up to 45 seconds, because MCP clients give a tool call about a minute. To keep waiting, the agent calls again with ask, not with the question again, and meanwhile it can go on with anything that doesn't depend on the answer.

Returns the answer, and PacedMind records You answered in PacedMind, and Claude Code went on: and the start of it:

The user answered:
ISO dates, like 2026-09-28.

With no answer yet:

No answer yet. To keep waiting, call ask_user again with ask 4d6a0c2e-9b1f-4f7e-8a53-1c2d3e4f5a6b (not the question again), or go on with what you can do meanwhile.

After 30 minutes without an answer: The user didn't answer within 30 minutes. Hand the task back with finish_task, outcome blocked, and the question in questions.

Refused when:

• the task has no running session (DEV-22 has no running session. Call start_task with task DEV-22 first.);
• a session PacedMind started names another task or session (This session works on DEV-21 (session 3f2a9c1b); it can only report on that task.);
• there's neither a question nor an ask (Pass your question, or the ask a previous call returned.);
• ask isn't one of the session's questions (This session has no such question. Ask it again with question.);
• the question was closed without an answer (The user didn't answer in time. Ask again, ask in this conversation, or hand the task back as blocked.).

finish_task

Changes data. Allowed without asking.

Hands a task back for the user's review, with a report of what the agent did. PacedMind shows the report on the task and in Sessions: the summary, the answer to each Done when item, the screenshots, how to check the result, and the questions. See The report.

Answers in criteria match the Done when items by number, by their text, or by a part of the text that fits only one item. The report keeps each item's text as it was at the hand-back, so later edits to the list don't change it. An answer that matches no item is kept as an extra item, so an agent can also report what it checked on a task without Done when items. Items without an answer show as not answered. The images the agent attached with attach_image while it worked become part of the report too. Links without a URL, and follow-ups that aren't task keys, are left out.

The report goes to the session named in session, else the task's running session, else its latest session when that one has already handed the task back. When there's no session to report on, as for an agent that PacedMind didn't start, finish_task records one (Started outside PacedMind), except for a task that is the user's own.

The session becomes Finished, with the summary as its note, which notifications and list_sessions show, and the task goes to In review. Nothing starts by itself. Tasks that wait for this one (dependencies) count it as finished when outcome is done. After partial or blocked, they wait until the user marks it done, until the agent hands it back again as done (for example after request_changes), or until a newer session of the task is marked finished. See Partly done or blocked.

The result starts with Recorded your report for DEV-22 (…). It waits for the user's check. The parentheses count the Done when items met and not answered, the images and the questions, or say summary only. When they apply, Not answered: follows with the items left without an answer, unless the outcome is blocked, and Left out follow-ups that aren't PacedMind tasks: with the keys. For partial or blocked, the next line says what waits: You handed it back as partial: tasks that wait for DEV-22 wait until the user marks it done. The result ends with You can stop here.

For example:

Recorded your report for DEV-21 (2 of 3 Done when items met · 1 question). It waits for the user's check.
You can stop here.

Recorded your report for DEV-22 (1 of 3 Done when items met · 1 not answered). It waits for the user's check.
Not answered: "A screenshot of the task panel with the running session".
You handed it back as partial: tasks that wait for DEV-22 wait until the user marks it done.
You can stop here.

Refused, with nothing recorded, when:

• the summary is missing (finish_task needs a summary: one or two sentences on what changed and what the user should look at first.);
• the task has Done when items, criteria is empty and the outcome isn't blocked: DEV-22 lists what "done" means. Answer each item in criteria (verdict met, partly or not_met, with a note), then call finish_task again:, followed by the numbered items;
• an item number doesn't exist (DEV-22's Done when has 3 items; there's no item 4., or, for a task without Done when items, DEV-22 has no Done when items. Pass the text of what you checked as item.);
• an image can't be used, with the same messages as attach_image; with several images, they end with Nothing was recorded; fix it and call again.;
• there's no session to report on and the task is the user's own (DEV-22 is marked as the user's own task (human), so it never gets an agent session. Ask the user before changing that with update_task.).

A session that can't call finish_task, in the cloud or in a desktop app without PacedMind's MCP server, is marked finished in the app instead, with Mark finished. That has the same effect on the session and the task, but records no report.