Skip to guide
Hormesis LabsDownload

Install Hormesis Workspace (open alpha)

On this page

Workspace runs Claude Code and Codex in its terminal panes using your own CLI accounts, and shows Workspace agents on a map. This page takes you from download to a first agent.

What you need

  • A Mac on macOS 12 (Monterey) or later. Apple Silicon or Intel.

  • Claude Code or the Codex CLI, installed and signed in. At least one. Workspace does not install them and has no sign-in of its own.

  • Your own Anthropic or OpenAI account. Agents run on your accounts. Workspace does not resell or proxy model access.

  • Node.js. Workspace's hooks and tools for the CLIs run on it. Check with node --version. If it is missing, install it from https://nodejs.org.

    Without Node.js, Workspace cannot install the hooks and tools that need it. Agents can still run, but status and Needs you may be incomplete. Workspace shows a Node.js notice with Check again.

Download and install

  1. Download the build for your chip: Hormesis-Workspace-arm64.dmg for Apple Silicon, Hormesis-Workspace-x64.dmg for Intel. Apple menu → About This Mac tells you which you have.
  2. Open the DMG and drag Hormesis Workspace onto Applications. Eject the DMG.
  3. Open the app from Applications. macOS may ask whether to open an app downloaded from the internet; click Open.

If macOS says the app is damaged or cannot be checked, do not work round it. Delete the download and tell us (see Troubleshooting).

First launch: the five Welcome steps

  1. Welcome. Three short hints about the map. Next, or Skip setup.
  2. Your agents. Shows whether Claude Code and Codex CLI were found, and where. A missing one has an Install button that opens its vendor's page. Install it, come back and click Check again.
  3. Connect Workspace to your agents. Lists the main changes to your CLI configuration. Workspace asks before changing your global CLI integration settings. Allow these changes or Not now.
  4. Add your first project. A project is a folder. Choose a folder, let Workspace find projects in a folder, or open the made-up sample project.
  5. Start your first agent. Start Claude or Start Codex opens the agent in its own pane and puts its card on the map. If the CLI is not signed in, it shows its own sign-in screen in the pane.

macOS may also ask whether Workspace may send notifications.

What Workspace adds to your Claude and Codex settings

After Allow these changes, Workspace merges its integration entries into the settings below and writes its skill files. Existing JSON may be reformatted.

  • Claude: an MCP server (hormesis-workspace) in ~/.claude.json; hooks in ~/.claude/settings.json that report agent state, deliver queued messages and guard subagent starts; a skill in ~/.claude/skills/hormesis-workspace/.
  • Codex, if it is installed: a skill in ~/.agents/skills/hormesis-workspace/. With Node.js available, also MCP and notify entries in config.toml and hooks in hooks.json, under CODEX_HOME or ~/.codex when that is unset.
  • Optional: Enable usage can add a Workspace status line to a Claude account profile.

Workspace snapshots the original files in its app-data folder. Changed existing configuration files also get a .bak copy beside them; skill files do not.

To remove it: Settings → Claude & Codex → Remove Workspace from Claude and Codex removes the default integrations listed there. If nothing else edited those files in between, their original contents are restored. Check any error it reports. Additional account profiles are not covered by this button and need separate clean-up.

If you choose Not now, agents can still run, but Workspace tools and hook-based status are unavailable. Some screen-based notices may still appear.

Updates

Workspace checks for an update when it starts and every four hours, and downloads it in the background. When it is ready you see Update ready with Restart now and Later. Nothing restarts until you say so.

Uninstall

  1. Settings → Claude & Codex → Remove Workspace from Claude and Codex. Do this first.
  2. Quit Workspace and drag it from Applications to the Trash.
  3. Optionally delete ~/Library/Application Support/hormesis-workspace and ~/Library/Logs/Hormesis Workspace. This removes Workspace's data and its built-in sample project. Project folders stored elsewhere are not deleted by these steps.

If you trashed the app without clicking Remove, Claude Code and Codex keep entries for a server that is no longer there. Reinstall Workspace and click Remove: that is the supported clean-up. To do it by hand, see Troubleshooting.

Privacy

  • Workspace stores its workspace records on your Mac. Claude Code and Codex may send prompts and project content to their providers under their own settings and policies, as they do in your own terminal.
  • Workspace contacts our server to check for updates and download them.
  • Crash dumps are written to your Mac (~/Library/Application Support/hormesis-workspace/Crashpad) and are not uploaded.
  • Help → Report a bug… opens a draft with the app version, macOS version, chip, architecture and a report template. Workspace does not send it; you review and send it in your mail program.