Troubleshooting

Start with the failing agent or command, then check Runner's settings and diagnostics. The steps below preserve existing chats and missions while you identify the problem.

Runner does not open

Runner starts its background service before showing a window. If that fails, Runner records the reason in runner.log and, on Windows, shows it in a Runner could not start dialog. The log is in ~/Library/Logs/com.wycstudios.runner on macOS and %APPDATA%\com.wycstudios.runner\logs on Windows. Include the message when you report the problem.

An agent is missing or fails to start

1. Run the agent in your usual terminal. If it cannot start or sign in there, finish its own setup first.
2. Open Settings → Agents. Enable the runtime and click Refresh. Use Browse to select the actual executable if Runner did not find it on PATH.
3. Check the chat's working directory and model choice. Select a model available to that agent and account, or use its default.
4. Read the terminal for an authentication, folder trust or provider error. Runner cannot complete the provider's login for you.

On Windows, npm shims need Node.js, and Claude Code and pi's bash tool need Git for Windows. Cursor, Grok and other newer integrations have platform-specific validation gaps listed under Supported agents. An enabled runtime is not a guarantee that its provider supports every platform.

The runner command is missing

Open Settings → General → Command line and inspect the installation status. On macOS, use Install if necessary. On Windows, open a new terminal after Runner adds the command to your user PATH.

Check which command your shell finds:

command -v runner
runner --version

In PowerShell:

Get-Command runner
runner --version

If another executable named runner comes first, use the path shown in Settings or correct your shell's PATH order. Restart the agent session if it inherited an older environment.

A sandbox blocks Runner

Exit code 5 means the calling sandbox prevented access to the local service. It does not mean Runner is closed. Ask the calling agent to retry the same command with its host's permission mechanism outside the sandbox. For code 3, open Runner and retry. Exit codes explains other failures.

A stopped conversation did not resume

Check Settings → General → Resume running agents on launch. Only agents recorded as running at shutdown are candidates for automatic recovery; a manually stopped chat needs Resume.

Read the session's error and terminal output. Resume needs a saved conversation identity and the runtime's own history. If the agent changed conversations using its native commands, whether Runner tracks that change depends on the runtime. A new chat cannot reconstruct missing provider history.

For a mission slot, Restart intentionally starts a fresh conversation. Use Resume when you want continuity. Restore archived work from Settings → Archived before trying to resume it.

The mission looks idle or the feed watch ended

Open the member's terminal to check for a login, approval or unfinished prompt. Some runtimes use terminal activity to estimate working and idle; the marker is not a completion signal.

For a CLI watch, run runner mission show <mission-id> --json and read stderr from the follower. The follower can exit when all sessions stop, when the mission ends, or on a connection error. If work is still active, follow the resume command printed by the watcher. After resuming a stopped mission, start a new watch.

MCP or skill changes do not appear

Start a new session after changing a registration or global skill switch. These edits affect the runtime's own files; a running process may have already loaded its configuration. Check the path and selected agent in Settings, and use Refresh after an external edit. Some skill catalogs deliberately omit bundled, project or plugin skills; see MCP servers and skills.

Collect a useful bug report

Find the Runner version in Runner → About Runner on macOS, or Settings → About on either platform. The macOS About window shows the app icon, version and build identity, and copyright. Released builds include their commit identifier; local development builds show dev.

Open Settings → Diagnostics → Open log folder. Include the Runner version, operating system, agent CLI and version, the steps that failed, and the visible error in a GitHub issue. Share only the relevant log excerpt after removing secrets and private conversation content. Keep the original sessions and logs until you have captured the evidence; deleting application data is not a first troubleshooting step.