Skip to content
Catalyst Catalyst Catalyst

Install Catalyst

Get Catalyst installed and running in about five minutes.

What you need first

Section titled “What you need first”
  • macOS — Catalyst is built and tested on macOS only.
  • Claude Code — install it before you start.
  • Git — needed to detect your repo and run the thoughts system.

The setup script installs the rest for you: jq, sqlite3, the HumanLayer CLI, and Bun (the runtime behind the dashboard and broker). It also offers to set up optional tools — the GitHub CLI (gh), the Linearis CLI, agent-browser, and direnv.

1. Run the setup script

Section titled “1. Run the setup script”
Terminal window
curl -O https://raw.githubusercontent.com/coalesce-labs/catalyst/main/setup-catalyst.sh
chmod +x setup-catalyst.sh
./setup-catalyst.sh

It checks your platform, installs the prerequisites, creates your project config, sets up a shared thoughts repository, and asks for any API tokens (like Linear).

2. Install the plugin

Section titled “2. Install the plugin”

In Claude Code:

Terminal window
/plugin marketplace add coalesce-labs/catalyst
/plugin install catalyst-dev

Restart Claude Code after installing.

On a headless or SSH-only host, install from the shell instead:

Terminal window
claude plugin marketplace add coalesce-labs/catalyst
claude plugin install catalyst-dev@catalyst

3. Install the command-line tools

Section titled “3. Install the command-line tools”

Several Catalyst features call shell tools by name (catalyst-monitor, catalyst-hud, catalyst-events, and more — see the full CLI command reference). Install them onto your PATH:

Terminal window
shopt -s nullglob
_cli=( ~/.claude/plugins/cache/catalyst/catalyst-dev/*/scripts/install-cli.sh )
[ ${#_cli[@]} -gt 0 ] && bash "${_cli[0]}" || echo "catalyst-dev plugin not installed — run step 2 first"

They install to $HOME/.catalyst/bin. If that folder isn’t on your PATH, the installer adds it to your shell’s startup file. Open a new terminal to pick up the change, then check it worked:

Terminal window
which catalyst-events
catalyst-events help

4. Start the stack

Section titled “4. Start the stack”

Bring the three core Catalyst services up in dependency order (monitor → broker → execution-core), plus the opt-in mitmproxy capture service if you pass --proxy:

Terminal window
catalyst-stack start

Run this once after each reboot or after pulling new code. See catalyst-stack reference for flags including --hotpatch (apply an update without reinstalling) and --proxy (opt-in Linear traffic capture via mitmproxy).

The stack is three long-running services (plus an opt-in proxy):

  • catalyst-broker — the event bus every agent and the executor read and write through.
  • catalyst-monitor — watches your GitHub PRs and CI status and emits events.
  • catalyst-execution-core — the scheduler: it picks up Todo tickets and dispatches the phase-agent workers.
  • mitmproxy (opt-in, --proxy only) — logs Linear API traffic.

See the catalyst-stack reference for the full command set.

5. Add Catalyst to your project

Section titled “5. Add Catalyst to your project”

Copy the Catalyst snippet into your project’s CLAUDE.md so Claude Code knows the available workflows:

Terminal window
cat ~/.claude/plugins/cache/catalyst/catalyst-dev/*/templates/CLAUDE_SNIPPET.md >> .claude/CLAUDE.md

6. Try it

Section titled “6. Try it”

Start a Claude Code session and run:

/catalyst-dev:research-codebase

Follow the prompts. Catalyst spawns helper agents, documents what your code does, and saves the findings to thoughts/shared/research/.

Optional plugins

Section titled “Optional plugins”

Catalyst is a set of plugins. Install only what you need:

Terminal window
/plugin install catalyst-pm           # product strategy
/plugin install catalyst-pm-ops       # cycle, backlog, and cadence ops
/plugin install catalyst-analytics    # PostHog analytics
/plugin install catalyst-debugging    # Sentry error monitoring
/plugin install catalyst-meta         # workflow discovery

See Plugins for what each one does.

Keeping plugins up to date

Section titled “Keeping plugins up to date”

Claude Code checks for plugin updates when a session starts and pulls them automatically. Restart Claude Code to load a new version. To force an update now:

Terminal window
/plugins update

Check your installed versions any time with /plugins.

Next steps

Section titled “Next steps”