Troubleshooting

The app

PacedMind could not start

The dialog PacedMind could not start. appears when the app's server stops while starting (The server stopped while starting.) or doesn't answer within 30 seconds (The server did not answer within 30 seconds.). It asks whether something else is using port 4319, the usual cause.

1. Check whether another program uses the port:
   • Windows, in PowerShell: Get-NetTCPConnection -LocalPort 4319. The owning process id is in the OwningProcess column.
   • macOS, in Terminal: lsof -nP -iTCP:4319 -sTCP:LISTEN. The process id is in the PID column.
2. If it's a PacedMind server left over from a crash that no longer answers, end it: on Windows, Organizer.exe in Task Manager; on macOS, kill followed by the process id, in Terminal. A leftover server that still answers is reused on its own.
3. Select Try again.

Open log opens the server log and closes PacedMind; start it again after reading the log.

PacedMind's server stopped

The dialog PacedMind's server stopped. shows the exit code and the log's location. Restart starts the server again; Open log opens the log and restarts the server too; Quit closes PacedMind.

The data looks empty, or the icon is blank

On Windows, Claude's and Codex's desktop apps keep a separate copy of AppData for the programs they start. When PacedMind is installed or started from a terminal inside one of them, it can open a second, separate database, and its shortcuts can lose their icon.

• Quit that copy (tray icon → Quit PacedMind) and open PacedMind from the Start Menu.
• Run npm run desktop from a terminal that wasn't started by those apps, such as Windows Terminal opened from the Start Menu.

The window doesn't open

PacedMind may be running without its window:

• Windows: it's in the tray. Click its tray icon, or open it from the Start Menu, which brings the existing window forward.
• macOS: it's in the menu bar. Click its Dock icon, or select Open PacedMind in the menu bar icon's menu.

With Start with Windows or Open at Login on, PacedMind starts without its window after signing in.

A page doesn't show the latest changes

Views refresh on their own a few seconds after data changes, while the window is visible. Press Ctrl+R (⌘+R on macOS) to reload.

"Organizer only answers on 127.0.0.1"

PacedMind was opened through another address than 127.0.0.1 or localhost. Use http://127.0.0.1:4319. The server refuses other host names on purpose; see Where your data lives.

Agent sessions

A session couldn't start

The task's details and Sessions show Couldn't start: and the reason, or a message appears when starting:

An agent can't start a session on another computer

An agent asks your other computers for sessions with start_session, and its answer says what became of the request:

See When an agent asks.

The terminal opens, but the agent doesn't start

The terminal shows an error such as 'claude' is not recognized as an internal or external command on Windows, or claude: command not found on macOS. The agent isn't installed, or isn't on the PATH that the session sees.

• Check in a new terminal that claude --version or codex --version works. Settings → General shows what PacedMind found, under Agents found here: a row without CLI, such as Claude app 1.4 or Not found, means it didn't find the command-line tool, on the PATH or where the installers put it.
• Or enter the agent's full path in Settings → Sessions (Claude command, Codex command). The command is used as typed, so put a path with spaces in double quotes, such as "C:\Program Files\Tools\claude.exe".
• On Windows, after installing an agent, quit and restart PacedMind, so it sees the new PATH. On macOS, each session starts in a new login shell, which reads the PATH from your shell's settings, such as ~/.zshrc.

The Codex app doesn't install the Codex command-line tool. Without it, run Codex sessions in the Codex app.

Then close the stuck session with Close session and start a new one.

A session hasn't checked in

After 90 seconds without word from the agent, a running session shows … hasn't checked in yet. It may be waiting for you in its terminal. When Claude Code doesn't trust the session's folder yet, it shows Claude Code is asking whether you trust this folder. Choose “Yes, I trust this folder” in its terminal. right away. Switch to its terminal:

• The agent may be asking a question: to trust the folder, to sign in, or to approve a tool. Answer it. To Claude Code's question about the folder, Yes, I trust this folder lets the session go on; No, exit ends it. With Trust session folders on, PacedMind answers it before the session starts. See Trusting the folder.
• The agent may not reach PacedMind's MCP server. Check that PacedMind is running; see An agent can't reach PacedMind.
• If the agent is working but never called start_task, ask it to follow its first message.

In the Claude or Codex app, the session shows Opened in the Claude app. Send the first message there to start. instead: the app wrote the first message but waits for you to send it. When the agent works but PacedMind never hears from it, the app isn't connected to PacedMind: select Connect for the agent in Settings → MCP server, and Mark finished for this session when it's done.

If the session can't recover, select Close session and start a new one.

A session stays "running" after its terminal closed

Claude Code reports its exit to PacedMind, and so does Codex, through its hooks or once it exits in its terminal. A session whose terminal was killed while the agent ran, or a Codex session whose window was closed before its hooks were trusted, stays running in PacedMind. To go on with it, select Reopen in terminal in the task's details or in Sessions: the conversation continues in a new terminal. To drop it, select Close session; the task goes back to Todo if it was in progress.

The agent lost PacedMind

While PacedMind is closed or restarting, such as during an update, a running agent can't reach it: it can't report or hand the task back, and may say so in its terminal. Once PacedMind runs again, tell the agent in its terminal to go on; if it still can't reach PacedMind, type /mcp there (Claude Code) and reconnect pacedmind. Or exit the agent and select Reopen in terminal, which continues the conversation in a new terminal with a fresh connection.

Sessions in a desktop app or the cloud don't report closing either. Select Mark finished when their work is done, or Close session to drop them.

A cloud session is running, but PacedMind shows nothing new

The cloud can't reach PacedMind on your computer. Follow a Claude Code on the web session at claude.ai/code, or in its terminal, and select Mark finished when its pull request is ready. PacedMind asks Codex about Codex cloud tasks every minute, using the Codex command-line tool, and marks them finished when they're ready; open the task from Sessions to see it.

Resume opens the wrong conversation, or none

• Claude Code resumes by its conversation id, shown in Sessions as Claude session. If that conversation was deleted, start a New session.
• Codex resumes by its conversation id, shown in Sessions as Codex session, once its hooks said which; before that, it continues its most recent session in the session's folder. To pick another one, run codex resume in that terminal.

An agent can't reach PacedMind

• PacedMind isn't running. Agents can only connect while the app runs, in the window, the tray or the menu bar.
• The token changed. After New token, select Connect for Claude Code and Codex in Settings → MCP server again. See MCP server.
• Wrong port. The desktop app uses 4319; a development copy started with npm run dev uses 4320. The Computers page says PacedMind: reports elsewhere in the agent's column when it's set up for another copy: select Connect in the copy it should report to.
• Claude Code: the tools are missing in one project. The server was registered for another project folder. Register it with --scope user. See Connect Claude Code.
• The tools are named mcp__organizer__…, or the skills mention the old name. The agent is connected under PacedMind's earlier name, which still works. Select Connect in Settings → MCP server to rename the entry to pacedmind.
• Codex app: the tools don't start. An older organizer section in ~/.codex/config.toml reads the token from ORGANIZER_TOKEN, which the app doesn't have. Select Connect in Settings → MCP server to write the token into the section. See Connect Codex.

Requests without the right token get 401 Unauthorized.

Request changes is missing, or doesn't reopen the session

Request changes, and Answer its questions, show only where they can send the work back: on the task's latest report, for a session that ran in a terminal on this computer, while no other session of the task runs, and not for your own tasks. When an agent sends changes with request_changes, or a request can't go through, the message says why:

When the terminal doesn't open, the message gives the reason, as when a session starts. See A session couldn't start.

The reopened session is a new conversation, for Claude Code too: the agent reads your changes or answers and its last report from start_task, not from its earlier conversation. To continue the earlier conversation itself, select Resume in terminal instead.

A session doesn't show that its agent waits for you

PacedMind hears that an agent waits for you only from sessions it started in a terminal. See When the agent waits for you.

• Sessions in a desktop app or the cloud have no hooks: look at the app, or the cloud session, yourself.
• Codex reports only the end of a turn until you trust PacedMind's hooks: choose Trust all and continue when it asks Hooks need review, or open /hooks in its terminal. A Codex older than 0.150 has none. A question Codex asks in its terminal never shows.
• Claude Code older than 2.1.84, and Codex, report through curl. Check that curl --version works in a new terminal. In PacedMind's Codex sessions, PacedMind's notify program takes the place of your own.
• The desktop app notifies once each time the agent starts waiting. If none appear, check the system's notification settings: see Notifications.

A session shows no usage

Only sessions PacedMind started in a terminal report what their agent used, and only once the agent has: every 30 seconds while it works, and when it exits. See What it used.

• Sessions in a desktop app or the cloud, and sessions started outside PacedMind, report nothing.
• Codex older than 0.150 reports nothing.
• Your own telemetry: when Claude Code's settings, its managed settings, Codex's config.toml or PacedMind's environment already send its telemetry somewhere (CLAUDE_CODE_ENABLE_TELEMETRY, OTEL_METRICS_EXPORTER, OTEL_EXPORTER_OTLP_…, or Codex's metrics_exporter), PacedMind leaves it alone. The same variables exported in your shell's startup files also take its place.
• A session started before this version of PacedMind reports nothing; its next one does.

A session says "Paused: usage limit"

Claude Code stopped because a usage limit of your plan, or your API credit, ran out; the session's line says what Claude Code said, such as when the limit resets. The session stays running. Claude Code may wait for the limit to reset and go on by itself; otherwise, write to it in its terminal once it has, or switch it to another model or account there.

A report has no Files changed, or says No diff

Files changed is there for sessions that started on this computer, in a terminal or a desktop app, in a folder that's in a git repository, and handed the task back with finish_task. See Files changed.

• No diff: PacedMind doesn't read folders in Desktop, Documents, Downloads or a cloud drive, where macOS asks first. PacedMind leaves those folders alone, so macOS doesn't stop it to ask. Keep projects somewhere else, such as a folder in your home folder.
• No diff: git wasn't there to compare the folder with. Install git. On macOS, PacedMind uses Homebrew's git, or Apple's once its command line tools are installed (xcode-select --install).
• Sessions in the cloud, started outside PacedMind, or started before this version have none.
• The diff itself stays on the computer the session ran on. Open PacedMind on that computer to see the full diff; the summary shows everywhere.

An image is missing from a report

Agents save screenshots as files first, and PacedMind keeps a copy of each: PNG, JPEG, GIF or WebP files of up to 20 MB. It refuses any other file with the reason, which the agent sees and can act on, such as after.bmp isn't a PNG, JPEG, GIF or WebP image. When the agent hands over several images at once and one of them fails, none is kept. Cloud sessions can't send images.

Dependencies

The next task didn't start

Nothing starts an agent session by itself: a dependency only says which task comes first. Once the task before it is finished, start the next one yourself, with Start with Claude Code in its details, or with Start session next to Waits for it: in Sessions. See Start a session.

A task still waits after the task before it finished

Check what it waits for, on the Timeline or in the Roadmap's task order:

1. Did the task before it hand its work back? A session in the cloud, or in a desktop app that isn't connected to PacedMind, can't. Select Mark finished for it.
2. Was it handed back partly done or blocked? Then the tasks after it wait until you mark it done: the label says Waits for you, or When you mark DEV-21 done. See Partly done or blocked.
3. Does it wait for other tasks too? A task is ready only when everything it waits for is finished.

A dependency can't be drawn on the timeline

The note while dragging explains the rule: dependencies stay within one project, can't form a loop, and can't make a finished task wait. See Timeline.

Planning

The week view plans nothing

• Work days or Focus hours in Settings → Planning leave no time, or the week's activities fill it.
• Your tasks have no due date, no planned day, and neither Urgent nor High priority, so the planner leaves them out.
• The tasks are handed to Claude Code or Codex. The planner leaves those to the agents.
• The tasks are in the backlog or in review.
• The switch next to the Auto-plan heading is off: the panel then says Auto-plan is off. Only fixed events are shown.

See The auto-planner.

A task "didn't fit this week"

Its estimate needs more time than the free focus time left. Lower the estimate, move it to a later week with Start, free up time, or extend the work hours.

Data

A task kept its old key after moving

Task keys never change, so links and agents keep finding the task. See Tasks.

Where are the logs and the data?

The menu of the tray icon (the menu bar icon on macOS) has Open data folder and Open server log. See Where your data lives.