How a session runs

A session moves through a few states. PacedMind changes them when it starts the session and when you act; the agent changes them by calling two MCP tools, start_task and finish_task.

States

A terminal session whose agent has not checked in after about 90 seconds shows Check agent startup and sends a notification. This applies to Claude Code and Codex, including a reopened session or Request changes. The agent is usually waiting for an answer there, for example to trust the folder or to sign in. See Troubleshooting. When Claude Code doesn't trust the session's folder yet, the session shows Claude Code is asking whether you trust this folder. Choose “Yes, I trust this folder” in its terminal. from the start instead: see Trusting the folder. In a desktop app, it immediately shows Send the first message and asks to press Enter or select Send there. Cloud sessions don't check in.

1. Start

When a session starts, from a task, from Sessions or at an agent's request, PacedMind:

1. checks that the task has no running session, that it isn't yours, that the computer has what the session needs, and that the task's folder is usable;
2. creates the session record, with an eight-character id, the agent, where it runs, the folder and a branch name such as agent/dev-22;
3. starts it where the task runs:
   • in a terminal: writes a start script, and for Claude Code the MCP connection and hooks that report when the agent waits for you and when the terminal closes (for Codex, hooks and a notify program that report the same), then opens a terminal titled with the key and the agent, such as DEV-22 · Claude Code, in the folder, runs the agent with its first message, and keeps the session Starting until its agent calls start_task;
   • in a desktop app: opens the app with a new session in the folder and the first message written (Opened in the Claude app on DESKTOP-1 (you started it here). Send the first message there to start.). The session stays Starting until the agent calls start_task;
   • in Claude Code on the web: opens a terminal in the folder that sends the task with claude --cloud, and marks the session Running (Sent to Claude Code on the web from a terminal in app: you started it here);
   • in Codex cloud: sends the task with codex cloud exec (Sending it to Codex cloud: you started it here), and marks the session Running with the task's link once Codex takes it on (Codex cloud took it on in the my-app environment);
4. sets the task's Done by to that agent, and moves a task in Todo or Backlog to In progress.

The session's first event says why it started:

The agent's first message starts with the task title and asks the agent to use it as the session name, then identifies the task and session for PacedMind:

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

New conversations opened through Request changes or Answer its questions receive the same title instruction. The agent controls the name it displays; existing conversations keep their names.

A cloud session can't call PacedMind's tools, so its first message carries the whole task instead: the key and title, the description, the Done when list, the sub-tasks as a checklist, and the instruction to work on a new branch named after the key, such as agent/dev-22, and to open a pull request when the work is ready for review.

2. Pick up

The agent calls start_task with the task key and the session id. PacedMind records Claude Code read the task over MCP and keeps the task In progress. PacedMind records what the session runs with first, such as Claude Code says it runs as …, with the MCP servers github, playwright, and which MCP servers it should have but hasn't, such as Not available to Claude Code: stripe needs you to sign in (/mcp in its terminal). See What a session actually has. The agent receives:

• after Request changes, first the changes you asked for, with the instruction to make them before anything else; after Answer its questions, your answers, with the instruction to go on with the task using them;
• the task: title, status, priority, dates, estimate, labels, its folder and where its sessions run, the description, the numbered Done when items, the numbered sub-tasks, the tasks it waits for and those that wait for it, and its latest report;
• the instruction to hand the task back with finish_task, the task key, the session id and a report: a summary, an answer to each Done when item, screenshots of anything it changed that can be seen, how to check the result and its questions. If it can't finish, it still hands the task back, partly done or blocked. It doesn't mark the task done itself.

3. Work

The agent works in the task's folder as it normally does, in conversation with you in its terminal or app. With PacedMind's agent skills installed, it also:

• ticks off sub-tasks as it completes them, and adds the ones it discovers;
• records work it finds outside the task, such as a bug elsewhere, as new tasks in the same project, and lists them in its report.

It keeps you posted with report_progress, only when it matters:

• its plan, once it has one, sent again as steps get done. While the session runs, the latest plan shows as Plan in the task's details and in Sessions, with the done steps ticked off and a count such as 2 of 5 done · 14:05;
• a problem that changes the scope or the risk (Claude Code ran into a problem: …).

When it needs a decision from you before it can go on, it asks with ask_user and waits for your answer (Claude Code asks you: …). The session then waits for you, as below, and you answer in PacedMind. See Answer while it works.

It can attach screenshots as it goes, with attach_image. They show under Images so far in the task's details and in Sessions, and join its report when it hands the task back. PacedMind shows all these changes as they happen.

4. Hand back

When the work is ready to check, the agent calls finish_task with its report: the summary, its answer to each Done when item, images, how to check the result, questions, details, links and follow-ups. See The report. PacedMind then:

• marks the session Finished, with the time and the report's summary as its note;
• moves the task to In review;
• notifies you, such as DEV-21 is finished · 1 question for you, and counts the session in the sidebar under Sessions.

Nothing starts by itself. Tasks that wait for this one (dependencies) no longer wait for it, and you start them when you choose.

An agent that can't finish everything hands the task back too, so the session doesn't look busy forever: Partly done when only part of it is ready, Blocked when it can't go on without you, with the decision it needs among its questions. After such a hand-back, the tasks that wait for this one keep waiting until you mark it done. See Partly done or blocked.

A session that can't call finish_task, in the cloud or in a desktop app that isn't connected to PacedMind, is handed back with Mark finished (You marked it finished). PacedMind hands back Codex cloud sessions itself when their task is ready, with a note such as Codex cloud finished: Add the auto-planner, +120 −8 in 4 files. Neither brings a report.

5. Review

Check the result: the agent's report, its terminal or app, and the changed files, or the pull request of a cloud session. Then:

• Mark done marks the task done. Its finished sessions count as reviewed (You marked it done) and show as Done.
• Request changes, for a session in a terminal on this computer, adds what should change to the report and reopens the session in a new terminal, in a new conversation (You asked for changes: …). The task goes back to In progress, and the agent reads your changes first when it calls start_task.
• Answer its questions, when its report asks you something, sends your answers the same way (You answered its questions: …).
• Or switch to the still-open terminal or app, or select Resume in terminal, and continue the conversation. The agent picks the task up again with start_task.

Either way, the agent hands the task back with finish_task and a new report when it's done.

See Review finished work.

When the agent waits for you

While a session runs, PacedMind hears when its agent stops to wait for you in its terminal, and shows it with a navy dot until the agent goes on:

In the task list, hover over the words to read the whole line; on a phone, only the dot shows. In Sessions, the session moves under Needs attention, with a navy dot like a finished one. The desktop app notifies once each time the agent starts waiting, with the task's title and the line above, and a click opens the session; the tray icon's tooltip counts these sessions with the finished ones. See Notifications.

The session is back at work as soon as the agent is: when you answer in its terminal (You answered in its terminal, and Claude Code went on), when you answer its question in PacedMind (You answered in PacedMind, and Claude Code went on: …), when you allow what it asked (You allowed it in its terminal, and Claude Code went on), or when it calls PacedMind again (Claude Code went on). After a usage limit: when Claude Code waited for the limit to reset and went on by itself (The usage limit reset, and Claude Code went on), when you write in its terminal (You wrote in its terminal, and Claude Code went on), or when it runs a tool again (Claude Code went on).

How PacedMind hears it depends on the agent:

• Claude Code in a terminal: the hooks PacedMind installs for the session report when its turn ends, when an error from the API ends it (such as a usage limit), when it shows a permission prompt or a question, or a reminder that it's still waiting, when it goes on after a usage limit reset, when you send it a message, and, while it waits for your permission or after a usage limit, when it runs a tool.
• Codex in a terminal: the hooks PacedMind gives the session report when its turn ends, when it asks for your permission, when you send it a message, and, while it waits for your permission, when it runs the tool. Codex runs them once you've trusted them: the first time, it asks Hooks need review in its terminal; choose Trust all and continue. They're the same in every session, so it asks once per computer. Until then, and with a Codex older than 0.150, only the end of a turn shows (its notify program), and PacedMind hears it went on when it next calls PacedMind. PacedMind also checks Codex's local turn records for capacity failures and other errors, even before its hooks are trusted. A new turn clears the error notice. Codex has no hook for a question it asks in its terminal.
• Desktop apps have no such hooks. PacedMind immediately shows Send the first message on opening a session; after check-in, only the questions the agent asks with ask_user or report_progress show there. Sessions in the cloud can't reach PacedMind.

What changed in git

When a session starts on this computer, in a terminal or a desktop app, in a folder that's in a git repository, PacedMind notes where the folder stands: its commit, whether it has changes that aren't committed, and the files git doesn't track. When the agent hands the task back with finish_task, PacedMind compares the folder with that and adds what changed to the report, under Files changed. See Files changed.

What it used

A session PacedMind starts in a terminal reports what its agent used: the tokens it read and wrote, and how long it worked. It shows

• in Sessions, in the session's details: Working, Tokens and Model. See Session details;
• in the task's details, as Usage, for all the task's sessions: 262k tokens · 1 min working · 1 session;
• in a project's header, for all its tasks: agents: 1.2M tokens;
• to agents, in list_sessions (used …) and get_task (Agents used: …).

Tokens count everything the agent read and wrote, most of it read again from its cache.

The agents send these numbers themselves, as usage metrics (OpenTelemetry), to PacedMind on your computer every 30 seconds and when they exit, with the session's own token. PacedMind keeps only the numbers and the model's name: what else the metrics carry, such as the account's email, is dropped as it arrives. No messages are sent, yours or the agent's.

• Claude Code reports tokens, its working time and the model.
• Codex 0.150 and later reports tokens, its working time and the model.
• Desktop apps and the cloud report nothing, and neither does a session started outside PacedMind.
• When you send Claude Code's or Codex's telemetry somewhere yourself, in its settings (Claude Code's settings.json, its managed settings, or Codex's config.toml) or in PacedMind's environment, PacedMind leaves it as it is, and those sessions report nothing.

Answer while it works

A question the agent asks with ask_user shows under the session's state line, in the task's details and in Sessions: Claude Code asks you, the question, and waits until 14:35, when PacedMind stops waiting for the answer, 30 minutes after the agent asked. Write your answer in the field marked Your answer and select Send answer, or press Ctrl+Enter or ⌘+Enter.

The agent gets the answer at once, or with its next call when it's between two: it waits in calls of 45 seconds and calls again until you answer. PacedMind records You answered in PacedMind, and Claude Code went on: and the start of your answer, and the session is back at work.

Without an answer in time, the question goes away and the agent is told to hand the task back as blocked, with the question among its questions. Answer it then with Answer its questions. See Answer the agent's questions.

When the terminal closes

• Claude Code reports its own exit through the hook PacedMind installed for the session, one per conversation: after Request changes, the terminal of the earlier conversation can close without affecting the session. A running session becomes Closed (Terminal closed before the agent finished); a finished one keeps its state and records Terminal closed. The task keeps its status, so a task that was In progress stays there until you change it or close the session.
• Codex reports its exit through the hook PacedMind gives the session, and, when that isn't trusted yet, through the session's start script once Codex exits: a running session becomes Closed (Terminal closed before the agent finished). A terminal window closed while Codex runs, before Codex's hooks are trusted, reports nothing: select Close session then.
• Desktop apps and the cloud don't report closing either. Their sessions stay open in PacedMind until they're marked finished or closed with Close session. Marking the task done also ends a cloud session.

Close session marks a session closed without touching the terminal (You closed the session) and sets a task in progress back to Todo.

Sessions started outside PacedMind

An agent that was started by hand, and connected to PacedMind over MCP, can report on a task too. When it calls start_task without a session id of that task, and the task has no running session, PacedMind creates a session record for it (Started outside PacedMind), with the project's folder, and the session appears in Sessions like any other. An agent that hands a task back with finish_task without a session to report on gets such a session too. PacedMind refuses this for tasks that are yours. Resume in terminal reopens such a session in its folder, or the task's when it has none. Claude Code starts a new conversation there, because PacedMind doesn't know the one the agent was in. See Resume a session.

A session you started yourself can also be attached to a task from Sessions, with the conversation it had. See Attach a session to a task.

Resume in terminal and Request changes reopen a session in the folder its conversation ran in, as Claude Code's or Codex's own record of it on that computer says, since Claude Code finds a conversation only from there. When that folder is gone, they use the task's folder.

What PacedMind records

Each session keeps a list of events, shown in Sessions under What PacedMind heard and at the bottom of the task's details: