Troubleshooting

Fixes for the problems people run into most, from sign-in to stuck threads.

An agent is missing or signed out

OpenOrc uses the agent CLIs installed on your computer and the sign-ins they already have. Settings, then Connections, shows each agent as Connected, Not logged in, Not installed, Fails to start, or Connection check failed. If no agent is ready when you come back to OpenOrc, it opens Reconnect your coding agent, which runs the same checks and shows each agent as Ready, Sign-in needed, Not installed, or Couldn't check.

For an agent that is Not installed, press its install button to open the setup guide, and install it.
For an agent that is Not logged in, run its sign-in command in a terminal: codex login, claude auth login, or opencode auth login.
Press Refresh connections in Settings, or Rescan on the setup screen.

When Claude Code signs out in the middle of your work, the thread shows Claude is signed out with a Sign in button. It opens the thread's Terminal and runs claude auth login there. Finish signing in, then send your message again.

Installed, but OpenOrc can't find it

On macOS and Linux, OpenOrc finds agents through your login shell, the way a new terminal window would. Open a new terminal and run command -v claude (or codex, or opencode). It has to print a full path. If it prints nothing, or an alias, add the agent's folder to PATH in your shell's startup file, then refresh.

OpenOrc gives your shell 8 seconds to answer. When it takes longer, agents keep starting with what the shell reported last time, but Connections shows Connection check failed until a check succeeds. Speed up your shell's startup files, then refresh.

On Windows, OpenOrc looks for agents on the PATH it started with. Add the agent's folder to PATH, or set OPENORC_CODEX_BIN, OPENORC_CLAUDE_BIN, or OPENORC_OPENCODE_BIN to its full path, then restart OpenOrc.

Fails to start

OpenOrc found the agent, but its --version command failed, so nothing can run through it. After an update check, a row OpenOrc can repair shows a reinstall button, such as Reinstall Claude. Otherwise reinstall the agent with the tool that installed it, and refresh. To see what OpenOrc sees, run claude --version (or codex, or opencode) in a terminal. For the sign-in, run claude auth status, codex login status, or opencode auth list.

A thread seems stuck

Check whether the agent is waiting for you. Its row in the sidebar says Needs your approval (or Needs approval and the command) or Has a question for you, and the thread shows the approval or question.
Press Stop (Stop this turn). With an empty message box, the Send button turns into Stop. Stopping keeps the session, so your next message continues where the agent was.
If nothing responds, not even Stop, reload the window: View, then Reload (⌘R). If OpenOrc's core had stopped, this starts a new one, and the interrupted run is marked as failed. Send a message to continue.

Other things that look like a stuck thread:

You see	What to do
A command marked Running above the message box	A command the agent left running, such as a dev server. It outlives the turn. Press its Stop when you are done with it.
The agent starts again after you stop it	Stop sends the next queued message. Remove queued messages you don't want first.
A queued message with Retry	Its delivery failed, or was cut off when OpenOrc closed, and it holds the messages behind it. Check the thread, then press Retry or remove it.
The last turn failed.	Send a message to resume, or press Retry with a fresh session.
Claude no longer has this session. (or Codex, or OpenCode)	Press Start a fresh session with a handoff. The new session gets a summary of your recent requests.
Usage limit reached.	Press Manage usage to see when the limit resets. For Codex, Use reset appears when your account has a reset to spend.

Approvals don't appear

An approval shows as a card in the thread, Allow followed by the tool's name, with Allow, Allow for this run, and Deny. The thread's row in the sidebar says it needs your approval, and the request is listed in the Inbox.

Check the mode. Autonomous, which Codex calls Full access, runs tools without asking. Accept edits changes files in the project without asking, and asks before commands and before edits outside the project. Codex's Ask for approval asks only for work outside its sandbox. See Modes and permissions.
Check notifications. A desktop notification comes only while Desktop notifications is on under General, your system allows notifications from OpenOrc, and you aren't looking at that thread.
After a restart. Pending approvals live only while OpenOrc runs. Quitting denies them, and the agent's turn ends.
For a request from Slack. The approval is posted in the Slack thread, and its buttons stop working after 10 minutes. It still waits in OpenOrc. Questions from the agent appear only in OpenOrc.

Slack doesn't reply

Make sure OpenOrc is open and your computer is awake. Slack can't reach an agent on a computer that is asleep or a closed app.
Open Settings, then Slack. After OpenOrc restarts, Slack isn't connected: press Connect and check. With a shared relay, press Connect this computer, and the host presses Save and connect relay.
If the status says Needs attention or Delivery pending, read the error under it and fix it. Then press Connect and check again, or Check connection while Slack is connected. A shared relay offers Retry Slack delivery or Reconnect to send result instead.
Mention the bot in a channel it was invited to, from the Slack member ID you entered. A personal bot ignores requests from anyone else.
Check that your default agent is signed in under Connections.

If the bot stays silent, check that both tokens came from the same Slack app. Replies sent with "Also send to channel" are never picked up. With a shared relay, OpenOrc also has to be open on the computer that hosts it.

The phone can't reach your computer

The phone's Home says why it isn't connected. The most common reasons:

The phone says	What to do
Phone access is off	On your computer, turn on Allow paired phones in Settings → Phone.
Not on its network	Join the same Wi-Fi as your computer, or turn on Tailscale on both.
Check Tailscale	Turn on Tailscale on the phone, and turn off any other VPN.
Not reachable or Reconnecting	Wake your computer and open OpenOrc. The phone connects only while both are running.
Needs an update	Update OpenOrc on the phone and on your computer.

If you removed the phone in Settings, or the pairing code expired before you scanned it, pair again with a new code. See Phone app.

Worktree and Git errors

Message	What to do
… isn't a git repository yet. Worktrees need git and a first commit.	Make the project a Git repository with at least one commit, or work in the Local checkout.
… has no commits yet. Worktrees need a first commit.	Make a first commit.
setup script exited with …	The project's setup script failed in the new worktree; the message ends with its last lines of output. Fix it in the project's Settings tab under Setup script. The worktree is kept and the script won't run there again, so run the missing steps in the thread's Terminal.
end the current turn before moving the thread	The agent is in the middle of a turn. Wait for it to finish, or stop it, then move again. Undo says the same with "restoring".
stop the thread's background commands before moving the thread	A command the agent left running, such as a dev server, would end with its agent. Stop it in the thread, then move again. Undo says the same with "restoring".
These files changed in both the worktree and the checkout: … Nothing was moved.	Commit or undo the changes on one side, then move again.
… is in use by … Finish or stop that operation before …	Another operation, such as an agent's turn or a commit, holds that folder. Wait for it, or stop it.
Push … to origin before opening its pull request.	Push the branch first. OpenOrc checks against the remote branches Git already knows about.
GitHub CLI (gh) is not installed …	Install `gh` and run `gh auth login`, or push and open the pull request in your browser.

Commits in a worktree can fail when the repository's Git hooks need dependencies the worktree doesn't have yet, such as node_modules. Install them in the setup script so every new worktree gets them. See Git and worktrees.

Updates won't install

OpenOrc installs an app update only when nothing is in the middle of work. When it can't, it says what to finish first:

A terminal still has a shell running. Use End shell in each terminal, then restart to update.
Wait for agent work, approvals, and context maintenance to finish before restarting to update.
Stop the background commands running in your conversations before restarting to update.
Wait for memory processing to finish before restarting to update.
Wait for agent updates to finish before restarting.
A schedule is starting a thread. Try again when it has started.
OpenOrc is processing a request. Try restarting to update again in a moment.

Closing a Terminal panel doesn't end its shell. Press End shell in each Terminal that still runs one, then restart to update.

If an installation fails, OpenOrc says The update could not be installed, or OpenOrc could not restart to update in the window. When your work has finished, quit and reopen OpenOrc, then try again. Linux releases don't update themselves: install the new rpm, deb, or AppImage over the old one.

Agent updates

OpenOrc refuses to update an agent while agent work, approvals, background commands, or background processing such as memory summaries are still running. Finish or stop them, then try again. Your conversations are kept. Some messages on an agent's row in Connections:

Message	Meaning
Update using the tool that installed this agent, then check again.	OpenOrc can't update this installation, for example one made with pnpm or bun, or any install on Windows. Update it yourself.
Update this installation with Homebrew, then check again.	Homebrew installed the agent in a way OpenOrc doesn't update, such as a formula or any OpenCode install. Upgrade it with `brew`.
The newer version is not active yet …	The update ran, but your package manager or release channel is still serving the old version. Check the installation in a terminal.
Reinstall using the tool that installed this agent, then check again.	The installation is broken and OpenOrc can't repair it. Reinstall the agent yourself.

If an agent shows Fails to start right after an update, its installation may be incomplete. Press the reinstall button on its row, such as Reinstall Codex, or reinstall it in a terminal.

Next steps

Known issuesLimitations and bugs we know about in the current version, with what to expect when you run into them.SettingsEvery settings section, what it controls, and where its choices are saved.How OpenOrc worksThe processes OpenOrc runs, how it talks to each agent, and the path a message takes from the composer and back.

Checked against OpenOrc's source on November 9, 2026.