Start, resume and close sessions

Start a session

A session can start from several places:

Nothing starts a session by itself: dependencies between tasks only order the work.

A message confirms the start, such as Started DEV-22 in a new terminal, Opened DEV-22 in the Claude app. Press Enter or select Send there to start., Sending DEV-22 to Claude Code on the web. The terminal shows its link. or Sending DEV-24 to Codex cloud. A session can't start when:

• the task already has a running session (DEV-22 already has a running session);
• the task is yours (DEV-22 is marked as yours. Hand it to Claude Code or Codex before starting a session.);
• the computer doesn't have what the place needs, such as The Codex CLI (codex) isn't installed on DESKTOP-1. Run it in the Codex app instead. or The Claude app isn't installed on DESKTOP-1.;
• the folder is unusable (see below);
• for the cloud, the folder isn't in a git repository (Claude Code on the web works on a git repository, and C:\code\notes isn't in one. Give DEV-22 or its project a repository folder.);
• for Codex cloud, the project has no Codex environment yet (Pick the Codex cloud environment Organizer app runs in first: its label from chatgpt.com/codex/settings/environments.).

When an agent asks

An agent you talk to asks for a session with start_session when you ask it to. Where the session would run decides what happens:

• On this computer, the request waits in PacedMind's window: a card, Start a session on this computer?, with the task, the agent and where it runs, the folder, and who asked (Asked by an agent over MCP), with Refuse and Allow, and a notification such as Start DEV-22 with Claude Code · Terminal?. Nothing starts until you allow it, within 10 minutes.
• On another of your computers, with an account: when the agent names that computer, or the task runs there, or the agent is connected to PacedMind Cloud. 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 is off takes it. That computer's From elsewhere setting then decides, as for any request without a code: Refuse, Ask me (the same card there, Asked by an agent, from elsewhere) or Start, at once. Where the code is on, the agent gets a link to the task instead, where you start it with Start and your code. A session started at once says so in its history: …: an agent's request from elsewhere, as this computer allows.

Switching a computer's two-factor code off lets the agents you connected ask it for sessions, and with Start they start at once, in a folder of that computer's, on a task whose text the agent may have written. Keep the code on for any computer where you wouldn't let an agent start another agent without you. See General.

Which agent runs

Unless an agent is chosen at the start, a session runs with the task's own agent (its Done by), else the project's default agent, else Claude Code. Starting a session also sets the task's Done by to the agent that ran it.

Where a session runs

A session runs in one of three places, chosen per task with Run in, in its details or in quick add, with the arrow next to Start with Claude Code, or by an agent with update_task:

Until a task's place is chosen, it runs in a terminal when the agent's command-line tool is installed on the computer, else in the agent's desktop app. PacedMind finds out what the computer has on its own, when it starts and every half hour.

A cloud session works on a copy of a repository. Claude Code on the web uses the folder's repository, from GitHub or uploaded when it has none there. Codex cloud uses the repository of the project's Codex environment, starting from the folder's current branch. The whole task goes with the first message, its title, description, Done when list and sub-tasks, with the instruction to work on a new branch named agent/ and the task key, and to open a pull request when it's ready. Starting a cloud session needs the agent's command-line tool on the computer, and sends the task to that agent's cloud.

Complete startup

A new terminal session stays Starting until its agent checks in with PacedMind. Both Claude Code and Codex can first need sign-in, folder trust, hook review or another choice. Answer those prompts in the existing terminal. If the agent has not checked in after about 90 seconds, PacedMind shows Check agent startup in the task and in Sessions, and sends a notification. If setup is complete, ask the agent to call PacedMind's start_task.

A session opened in the Claude app or Codex app immediately shows Send the first message and sends a notification. Open that app, complete any setup prompts and send the prepared message by pressing Enter or selecting Send. The launch link fills in the message; it does not submit it. For a first message submitted automatically, set the task's Run in to a terminal. Terminal setup prompts can still need an answer.

If the agent stops because its model is unavailable, PacedMind shows Paused: model at capacity, separately from Paused: usage limit. In the existing terminal, use /model to choose another available model and retry, or wait and retry later. PacedMind does not change the model automatically. Other failures show Paused: agent error with directions to check the terminal. A successful retry clears the notice when the agent starts another turn or uses a tool.

If the terminal says the conversation is open in another app, close that other view of the conversation and retry in the existing terminal. Use Reopen in terminal only after the old terminal has closed; opening more copies does not resolve the lock.

PacedMind reads Codex's local failed-turn records even when its hooks have not been trusted yet. Claude Code reports errors through its hooks. When neither source reports an exact cause, the startup notice asks to check the terminal rather than claiming to know which prompt is shown.

Where a session works

A session uses the first folder set in this order: the task's own folder, its project's folder, then its area's workspace. Set the task's Folder in its details, the project's folder in Settings → Projects or the Roadmap panel, and the area's workspace from … → Workspace… on the area or Settings → Projects → Area workspaces. A task's own folder suits work that shouldn't share the project's checkout, such as a second copy of the repository.

To keep an area's Codex sessions in an existing Codex project, choose that project's folder as the area's workspace; it's saved at once. Tasks and projects without their own folder inherit it, so they share one workspace. This is saved only on this computer.

An agent can ask for a folder too, with set_folder, when you tell it where a project, an area's workspace or a task's own folder is on one of your computers. The request only suggests the folder. The computer checks that it's there, then shows a card, Use a folder on this computer?, with what gets it, the folder and who asked, and a notification such as Use a folder for Organizer app?. Use it sets the folder, as choosing it here would (Organizer app uses C:\code\app here now); Refuse drops it. A request from an agent on this computer waits 30 minutes; one from elsewhere, up to a day for that computer. Read the path before you allow it: sessions for that project, area or task start there. See set_folder.

The folder must be an absolute path to an existing folder, without the characters " % ! ^ & | < > ` $. Otherwise the start is refused, before any session is recorded, with a message such as:

• Can't use the folder C:\code\app: That folder doesn't exist. Change it in Settings → Projects.
• … Use an absolute path, like C:\Users\Anna\code\my-app. Change it in Settings → Projects. The example is a code folder in your own home folder, such as /Users/anna/code/my-app on macOS.
• … That path is a file, not a folder. Change it in Settings → Projects.
• … The path contains characters that can't be passed to a terminal safely, with the list of characters, Change it in Settings → Projects.
• On macOS: … The path contains a backslash, which can't be passed to a terminal safely. Change it in Settings → Projects.

For a task's own folder, the message ends with Change it in the task's details. instead.

A task without a task folder, project folder or area workspace gets a scratch folder of its own: %APPDATA%\Organizer\data\workspaces\<task key>, such as …\workspaces\wrk-12, or on macOS ~/Library/Application Support/Organizer/data/workspaces/<task key>. The task's details show it as PacedMind's folder for this task. A configured folder that no longer exists is reported as an error; the session does not silently switch to a scratch folder.

Trusting the folder

The first time Claude Code or Codex starts in a folder, it asks whether you trust it, and waits for the answer before it reads its first message. Trusting a folder also lets the agent use that folder's own settings, hooks and MCP servers.

With Trust session folders on (Settings → Sessions, on by default, for each computer), PacedMind answers yes just before it starts, resumes or sends back a session, for that session's folder only, so the session never waits for it. It writes the answer where the agent keeps it: for Claude Code in its settings file (~/.claude.json), for Codex in its config.toml, for the folder's repository. A folder Codex was told not to trust stays that way. Give projects only folders whose settings and hooks you'd let an agent run.

With it off, answer in the session's terminal: Yes, I trust this folder in Claude Code, which remembers it for that folder, and the session goes on; No, exit ends the session, and Claude Code asks again next time. PacedMind then reads Claude Code's settings file to tell you the question is coming, for sessions in a terminal on this computer:

• in the task's details, under Start with Claude Code (and under the session card of an ended session): Claude Code first asks whether you trust the folder: choose “Yes, I trust this folder” in its terminal.;
• in the message after starting, resuming or Request changes, which ends with the same sentence;
• on the running session, until the agent checks in: Claude Code is asking whether you trust this folder. Choose “Yes, I trust this folder” in its terminal.

A scratch folder is new for every task, so without the setting Claude Code asks once for each task without a folder.

Every session also gets a branch name, agent/ and the task key, such as agent/dev-22. PacedMind records it with the session; it doesn't create or switch branches itself.

The terminal

Terminal in Settings → Sessions chooses where terminal sessions open. On Windows:

• Windows Terminal (the default): a new tab in a Windows Terminal window reserved for PacedMind's sessions. If Windows Terminal can't start, the session opens in a Command Prompt window instead.
• Command Prompt: a new Command Prompt window per session.

On macOS:

• Terminal (the default): a new Terminal window per session.
• iTerm: a new iTerm window per session. If iTerm isn't installed, the session opens in Terminal instead.

The tab or window is titled with the key and the agent, such as DEV-22 · Claude Code, or DEV-22 · Claude Code on the web for a cloud session. The terminal starts in the session's folder, with the environment variable ORGANIZER_TOKEN set to the session's own MCP access token, which works only for its task and only while it runs. PacedMind leaves out its own server's variables, such as PORT and NODE_ENV, so the agent's builds, tests and dev servers behave as they would in any terminal. When PacedMind itself runs inside a Claude Code session, such as a development copy started with npm run dev from Claude Code, it also leaves out that session's variables, such as CLAUDECODE: the agent then starts as a Claude Code session of its own, which keeps its own conversation. On macOS the session runs in a login shell, so the agent finds the same PATH as in a new Terminal window.

The agent command

Settings → Sessions has the command for each agent: claude and codex by default. Change them to add options or to use a full path, for example when the agent isn't on the PATH of programs started from PacedMind. With the default command, PacedMind also looks where the installers put the agents, and uses the one it finds there.

Claude Code starts with:

• the connection to PacedMind's MCP server, under the name pacedmind. If your own Claude Code settings still have PacedMind under its earlier name, organizer, the session gets that entry replaced by one that doesn't connect, so it only ever uses its own token; Connect renames your entry;
• hooks that tell PacedMind when the agent waits for you, asks for your permission or asks you something in its terminal, when it goes back to work, and when the terminal session ends. See When the agent waits for you. Claude Code 2.1.84 or later sends them to PacedMind itself; an older version runs curl for each;
• permission to use PacedMind's everyday tools without asking (below);
• a conversation id, so that Resume in terminal can continue the same conversation;
• the conversation named after the task, such as DEV-22 Start sessions from the app;
• the first message, which names the task and the session.

Codex starts with the first message and, for that session, the connection to PacedMind's MCP server under the name pacedmind, with the token from the ORGANIZER_TOKEN variable the terminal sets. This connection takes the place of the pacedmind entry in Codex's own configuration, headers included, and an entry under the earlier name, organizer, is switched off for the session, so the session only ever sends its own token, not the one Connect wrote there. Codex also gets a notify program for the session, which tells PacedMind with curl when a turn ends and Codex waits for you; it stands in for your own notify setting while the session runs. From Codex 0.150, it gets hooks too, which tell PacedMind when it asks for your permission, when you answer, when it goes back to work and when it ends, and which conversation it runs. They run PacedMind's hook script, codex-hook.sh (codex-hook.cmd on Windows) in PacedMind's data folder, which reads the session's address and token file from the terminal. Codex runs hooks only once you've trusted them, and asks the first time: Hooks need review, where Trust all and continue trusts them for every later session on the computer. With Answer from elsewhere on, a permission Codex asks for waits in PacedMind too, as for Claude Code. The Codex app, and Codex sessions you start yourself, need the pacedmind entry in Codex's own configuration instead. See Connect Codex.

When a project limits the MCP servers its sessions get on this computer, Claude Code starts with only those and PacedMind's, and Codex with the others switched off. See Other MCP servers, plugins and skills.

What agents may do without asking

Sessions PacedMind starts in a terminal reach PacedMind with a token of their own, which works only for their task, only while they run, and only for these 22 MCP tools:

• reading: get_overview, list_areas, list_projects, get_project, list_tasks, get_task, list_events, get_agenda, list_sessions, list_computers, get_settings, get_preferences, get_next_task;
• the session protocol: start_task, attach_image, report_progress, ask_user, finish_task;
• task notes: list_task_note_displays and show_task_note, for its own task when you ask for it. With several displays and no remembered choice, it asks which one and whether to remember it before showing a note;
• adding tasks and updating its own: create_task, for open tasks (to do or in the backlog), and update_task, for the session's own task, without its status, agent, project, area, where it runs, folder or needs.

Claude Code runs them without asking you first: PacedMind passes this list when it starts it. Codex follows its own approval settings.

The token doesn't list any other tool, and the others refuse it: Sessions that PacedMind started can't use delete_task. Ask the user to do it in PacedMind. So such a session can't delete anything, move calendar events, change projects or planner settings, ask for folders, start other sessions or send work back with request_changes, whatever it's asked. Apart from remembering your task-note display choice, preferences stay under your control in PacedMind or through an agent you connected yourself.

Sessions in the Claude app or the Codex app use your own connection to PacedMind (see Connect your agents), with every tool, and follow the apps' own approval settings.

Other MCP servers, plugins and skills

Besides PacedMind's MCP server, a session gets what Claude Code or Codex has on the computer and in the session's folder, as when you start them yourself: other MCP servers, plugins, skills and hooks, and the folder's instructions in CLAUDE.md and AGENTS.md. PacedMind reads their names from the agents' own settings files, without running anything, and shows them in two places:

• Computers, in each computer's Claude Code and Codex columns: MCP servers, one per line with the brand's mark, such as github and playwright, or None, then counts such as 1 plugin · 12 skills · 1 hook. That's what they have in every folder on that computer: Claude Code's servers for all projects, the plugins and hooks in its ~/.claude/settings.json and the skills in ~/.claude/skills, and Codex's servers, hooks and skills in ~/.codex.
• Settings → Projects, under each project: what the agents get in the project's folder on top of that, and which MCP servers its sessions get. See Settings.

Only names are shown. A server's command, address, headers and keys stay in the agents' files, and PacedMind's own pacedmind server isn't listed, since every session has it, nor is an entry under its earlier name, organizer.

What a session actually has

What the settings files name isn't always what a session gets: a server can fail to start or wait for you to sign in, the account Claude Code is signed in to adds its claude.ai connectors, and plugins add servers of their own. For a Claude Code session PacedMind started in a terminal, PacedMind reads what the session has from Claude Code's own record of it, the session's transcript, rather than from what the agent says, which can be wrong: an agent told a server failed can still list it.

• When the agent calls start_task, PacedMind records the MCP servers the session has tools from, such as Claude Code says it runs as …, with the MCP servers github; the claude.ai connectors Gmail, Linear; the servers of its plugins episodic-memory.
• When a server gave it no tools, PacedMind records Not available to Claude Code: and each one with why: needs you to sign in (/mcp in its terminal), didn't start with Claude Code's error code, such as (ENOENT), or hasn't connected yet. Sessions shows it as Not available.
• A server still connecting is looked at again 30 seconds later, and while one is missing, again at the end of each of the agent's turns. Once they're all there, PacedMind records All its MCP servers are available to Claude Code now, and Not available goes away: for example after you sign in with /mcp in the session's terminal.

Claude Code writes that record while it loads MCP tools on demand, its default. Codex's session records don't say how its servers are, so a Codex session, and a session in a desktop app, shows the servers its agent says it has.

The claude.ai connectors come from the Claude account Claude Code is signed in to on that computer, which no settings file names, so they can differ from computer to computer. Computers shows them for each computer as claude.ai connectors and their names, from the last session PacedMind started there that got all its servers (one of a project that picks its servers gets none of them).

Choose a project's MCP servers

Each project in Settings → Projects says which MCP servers its sessions get on this computer: MCP servers for its sessions: all they have here, only and their names, or none besides PacedMind. Change opens the choice, and Done closes it:

• All of them, the default: Sessions get every MCP server Claude Code and Codex have in this folder, as when you start them yourself.
• Only these: a switch for each server Claude Code or Codex has for the project's folder, with the agents that have it. Claude Code gets only these, and none from plugins or its claude.ai account; Codex has the others switched off. PacedMind's own server always stays.

The servers to choose from are, for Claude Code, yours for all projects, the ones it keeps for this folder only, and the ones in the folder's .mcp.json that you allowed there; for Codex, the ones in ~/.codex/config.toml and in the folder's .codex/config.toml. The choice is this computer's, like the project's folder, and applies to the terminal sessions PacedMind starts, resumes or sends back from then on. For Claude Code, PacedMind copies the chosen servers' settings into the session's own MCP configuration. Sessions in the desktop apps and the cloud get what the app or the cloud has.

Sessions shows what a session ran with: Client, the name and version its MCP client gave when it connected to PacedMind, such as Claude Code 2.1.278, Agent says, the model the agent reported with start_task and the MCP servers the session has, and Not available, the ones it should have but hasn't. See Session details.

What a task needs

Your computers can differ in what their agents have: each has its own MCP servers and plugins, and Claude Code on each can be signed in to a different Claude account, with other claude.ai connectors. A task's Needs says what its agent needs from the computer its session runs on, such as Gmail or supabase. List only what differs between computers: the MCP servers in a project's own folder, such as its .mcp.json, come with the project to every computer that has it.

PacedMind matches the needs against what each computer said its agent has: its MCP servers for all projects and, on this computer, in the task's folder, the claude.ai connectors its sessions got, and its plugins. Names match regardless of case, spaces and dashes, so google-drive matches Google Drive.

• Start on a computer whose agent lacks something the task needs still starts the session, and the message says what's missing, such as Started DEV-44 in a new terminal. Claude Code doesn't have Gmail here, which DEV-44 needs. When your data is in PacedMind Cloud and another of your computers has it all, Start opens Run on a computer with that computer picked instead, and Start here anyway to start on this one after all.
• Run on a computer shows, under each computer, Has Gmail or Doesn't have Gmail, and picks one that has everything the task needs, online first.
• A request that expired because its computer didn't answer offers Try another computer, which opens Run on a computer without that computer picked.

A session in the agent's cloud has the cloud's own servers, so needs aren't checked for it.

Resume a session

Resume Claude Code or Resume Codex in the task’s details (Resume in terminal in Sessions) opens a new terminal in the session's folder for a terminal session that isn't running:

• Claude Code continues the same conversation, with its full history.
• Codex continues the same conversation, once its hooks or local session record identified it (shown in Sessions as Codex session). If startup stopped before it created an identifiable conversation, PacedMind opens a fresh conversation with this task's first message.

PacedMind records Reopened in a terminal. A resumed session gets the current MCP access token, even if it was regenerated since. A session an agent reported on its own (Started outside PacedMind) resumes too, in its folder, or the task's when it has none. If PacedMind doesn't know that agent's conversation, it starts a new one on the task.

A session that still runs in PacedMind but whose terminal is gone (closed, crashed, or the computer restarted), or whose agent lost PacedMind and you closed its terminal, gets Reopen in terminal instead, on the computer it runs on. It asks first: Reopen this session in a new terminal? Do it when its terminal is gone. If it's still open, close it first: two terminals on one conversation get in each other's way. Then the conversation goes on in a new terminal, the same way, and PacedMind records Reopened in a new terminal. The new terminal gets a new access token for the session, so a terminal left behind can't report on it anymore, and a question the old terminal still waited on in PacedMind is withdrawn.

To send finished work back with what should change, use Request changes instead, or Answer its questions when the agent asked something: it adds what you wrote to the agent's report and reopens the session in a new terminal, in a new conversation, where the agent reads it first. See Request changes.

Sessions elsewhere have their own buttons:

Mark a session finished

A session in the cloud, or in a desktop app that isn't connected to PacedMind, can't hand its task back. Mark finished, in the task's details and in Sessions, does it for the session: the session becomes Finished (You marked it finished), without a report, and the task goes to In review. Review the work, then Mark done as for any session.

Close a session

Close session, for a running session, asks Close this session in PacedMind? The terminal stays open. (in Sessions, for a session outside a terminal: It keeps running where it is.), then marks the session Closed and sets a task in progress back to Todo. Use it when:

• a terminal was closed while its agent ran, and the agent couldn't report it (Codex before its hooks are trusted);
• a session got stuck before the agent checked in;
• the work should stop and start over.

After a session finishes, closes or fails, New session with Claude Code (or Codex) in the task’s details starts a fresh one, as long as the task isn’t done. It uses Done by, also editable beside Agent; the arrow beside the button can choose and start either agent in another place. Changing the agent starts a fresh conversation and keeps the previous session’s history. See Switch agents.

One running session per task

A task has at most one running session: starting another says DEV-22 already has a running session.