Skip to content
Catalyst Catalyst

Getting Started

Get Catalyst installed and working in your project in under 5 minutes.

Prerequisites

Section titled “Prerequisites”
  • macOS — Catalyst is built and tested on macOS only. Other platforms are unsupported.
  • Claude Code — Install Claude Code before running setup
  • Git — required for repository detection and thoughts system

The setup script checks for and installs additional dependencies automatically:

DependencyRequired?Auto-installed?
jqYesYes (via Homebrew or apt-get)
sqlite3YesIncluded with macOS
HumanLayer CLIYesYes (via pip)
GitHub CLI (gh)OptionalOpens install page
Linearis CLIOptionalShows npm install command
agent-browserOptionalShows npm install command
BunOptionalFor orch-monitor dashboard
direnvRecommendedPer-project env vars, API key isolation

Run the Setup Script

Section titled “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

The script will:

  • Verify platform (macOS) and check/install prerequisites (HumanLayer, jq, sqlite3)
  • Set up a thoughts repository (one per org)
  • Create project configuration
  • Configure worktree directories
  • Initialize the SQLite session database (~/catalyst/catalyst.db)
  • Prompt for API tokens (Linear, Sentry, etc.)
  • Link your project to shared thoughts

Install the Plugin

Section titled “Install the Plugin”

In Claude Code:

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

Restart Claude Code after installing.

Add Catalyst Context to Your Project

Section titled “Add Catalyst Context to Your Project”

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

Terminal window
cat plugins/dev/templates/CLAUDE_SNIPPET.md >> .claude/CLAUDE.md

Try It Out

Section titled “Try It Out”

Start a Claude Code session and run:

/research-codebase

Follow the prompts to research your codebase. Catalyst will spawn parallel agents, document what exists, and save findings to thoughts/shared/research/.

Optional Plugins

Section titled “Optional Plugins”

Catalyst is a 5-plugin system. Install what you need:

Terminal window
# Project management (Linear integration)
/plugin install catalyst-pm


# Analytics (PostHog integration)
/plugin install catalyst-analytics


# Debugging (Sentry integration)
/plugin install catalyst-debugging


# Workflow discovery (advanced users)
/plugin install catalyst-meta

Keeping Plugins Up to Date

Section titled “Keeping Plugins Up to Date”

Catalyst plugins are updated frequently. There are two ways to stay current.

Automatic Updates

Section titled “Automatic Updates”

Claude Code checks for plugin updates at session start. If a new version has been released, it pulls the update automatically. You just need to restart Claude Code (exit and reopen, or start a new session) to load the new version.

To confirm auto-updates are working, your plugins should show as installed from the marketplace:

Terminal window
/plugins

Manual Updates

Section titled “Manual Updates”

If you want to pull the latest right now — for example, a release just dropped — you can force an update:

Terminal window
# Fetch latest from the marketplace
/plugins update


# Restart Claude Code to load the new version

Checking Versions

Section titled “Checking Versions”
Terminal window
# See installed plugins and current versions
/plugins

Compare against the latest releases:

Next Steps

Section titled “Next Steps”