"Claude Code isn't installed" (or "Codex CLI isn't installed")
The card says this, and the pane prints "Couldn't start Claude Code. It isn't installed on this computer, or it isn't on your PATH."
Not installed. Install it from the vendor's page, then close the pane and start the agent again. Workspace does not install it for you.
- Claude Code: https://code.claude.com/docs/en/setup
- Codex CLI: https://developers.openai.com/codex/cli
Installed after you opened Workspace. In Welcome → Your agents, click Check again after installing a CLI. Then start a new agent pane.
Installed in ~/.local/bin. Workspace can launch a Claude Code it finds there even when that folder is not on your login PATH. If launch still fails, look in your shell configuration for something that replaces PATH, correct it if needed, and open a new pane. Do not change your shell profile only because which claude cannot find an installation Workspace already detects.
No status on the map, or Needs you stays empty
- Node.js is missing. Missing Node.js can prevent hook-based status and Workspace tools from working; some screen-based notices can still appear. If the Node.js notice appears (Welcome, or Settings → Claude & Codex), install Node.js from https://nodejs.org, then click Check again. Once setup is allowed, Workspace retries the parts it held back. Read any remaining error before starting a new agent pane.
- Workspace is not connected. Settings → Claude & Codex. If it says "Not connected", click Allow these changes.
- The agent was started before you connected. Close its pane and start a new one.
Update messages
Workspace normally logs a failed update check without a notification and tries again later.
- "Update could not be verified": the downloaded update was not offered for restart.
- "Update not installed": the download failed, or a local file error stopped it.
In both cases keep using the app you have. If a warning repeats, include its exact words and the app version in a bug report.
The sign-in hold: an agent is stopped at a sign-in screen
Claude Code or Codex shows its own sign-in screen in the pane, and Needs you says it asks you to sign in. Workspace types nothing into that screen.
Finish sign-in in the CLI and the browser. When the pane no longer shows sign-in or another dialog, click I've signed in on the Needs you item, or use Deliver now on a waiting message. The action is refused while a blocking screen is still showing.
An agent looks stuck
- Open its card and read the pane. A prompt may be waiting there: a permission question, a folder-trust question or a sign-in.
- Check Needs you and the hand badges.
- Open the Workspace health pill in the status bar. It lists agents that look stuck and agents a restart cut off.
- Read the pane before interrupting. Esc can interrupt a turn, dismiss a dialog or exit a CLI, depending on what is showing.
- "Queued · budget full" means the live agent budget is used up. Let an idle agent sleep, or raise the budget in Settings → Workspace.
Remove Workspace's entries by hand
The supported way is Settings → Claude & Codex → Remove. If the app is already gone, reinstall it and click Remove. By hand:
~/.claude.json: under"mcpServers", delete the"hormesis-workspace"entry.~/.claude/settings.json: remove only the hook commands that run Workspace'shook-toast.jsscript. Keep other hooks and the configuration around them.- Delete the folder
~/.claude/skills/hormesis-workspace. - Codex: in
CODEX_HOME, or~/.codexif that is unset, remove thehormesis-workspaceMCP section and only the notify and hook commands that run Workspace'scodex-notify.jsor Codex hook script. Delete~/.agents/skills/hormesis-workspace. Keep unrelated settings and hooks.
Some changed configuration files have a .bak copy beside them, but not every file does, and a .bak is not a permanent copy of your first setup.
Where the logs are
- App log:
~/Library/Logs/Hormesis Workspace/main.log - Crash dumps:
~/Library/Application Support/hormesis-workspace/Crashpad - Your data (projects list, settings, reports):
~/Library/Application Support/hormesis-workspace
In Finder: Go → Go to Folder…, and paste the path. Logs can contain project and file names, so read a log before you send it to anyone.
Report a bug
Help → Report a bug… opens a draft addressed to biro@hormesislabs.com with the app version, macOS version, chip, architecture and a report template. Workspace only opens the draft; you choose whether to send it from your mail program.
- If Workspace cannot open the mail link, it copies the report to the clipboard.
- Help → Copy bug report details copies the same details.
- Help → Save diagnostics… shows a short text file and saves it only where you choose.