Catalyst - Claude Code Workspace

A portable development workflow for Claude Code, packaged as a Claude Code plugin marketplace.

This is the workspace I use daily for AI-assisted development. It's battle-tested on real projects and optimized for efficient, context-aware AI collaboration. I'm sharing it so others can use it, fork it, and contribute ideas back.

Tech Stack & Integrations

Catalyst integrates with your development tools through both CLI-based (token-efficient) and MCP-based (richer features) approaches:

Project Management & Issue Tracking

• Linear - Issue tracking, sprint planning, ticket lifecycle (CLI via Linearis)
  • catalyst-dev: Core research agents and workflow commands
  • catalyst-pm-ops: Operational PM workflows (cycle analysis, milestone tracking, backlog grooming, cadence, comms)

Version Control & Code Hosting

• GitHub - Pull requests, code review, repository management (CLI via gh)
  • catalyst-dev: PR creation, branch management, worktree workflows

Documentation & Code Search

• Context7 - Library documentation lookup (MCP, ~2k tokens)
  • catalyst-dev: Built-in, always available
• Exa - Web research and external documentation (API)
  • catalyst-dev: External research agent

Thoughts & Memory System

• HumanLayer - Persistent memory, shared context, team collaboration (CLI via humanlayer)
  • All plugins: Foundation for research, plans, handoffs, and reports

Token Efficiency Strategy

Why CLI + lightweight MCP? Most development sessions don't need heavy integrations:

• Start with catalyst-dev (~3.5k tokens): Core workflow + Linear + GitHub
• Disable optional plugins when done to free context for code and conversation

This keeps your typical session lean while having powerful tools available when needed.

What's Inside

Catalyst is a 5-plugin system for Claude Code focused on token efficiency, session-aware MCP management, and persistent context through parallel agent research, structured handoffs, and shared memory systems.

catalyst-dev (Core - Always enabled)

• 9 research agents (codebase + infrastructure)
• 18 skills covering full dev lifecycle
• Three-tier model strategy (Opus for planning/implementation, Sonnet for CI/automation, Haiku for data collection)
• Linear integration via Linearis CLI
• Handoff system for context persistence
• ~3.5k context (lightweight MCP: Context7)

catalyst-pm-ops (Optional - Enable for Linear backlog grooming)

• 1 skill: groom-backlog — orphan / stale / duplicate ticket detection
• 1 specialized agent: catalyst-pm-ops:backlog-analyzer

catalyst-meta (Optional - For advanced users)

• 3 skills for workflow management
• Frontmatter validation across skills and agents
• Plugin health auditing and directory reorganization

Quick Setup (5 Minutes)

Get started in 5 minutes with the unified setup script:

One command, one key — works on a laptop, over SSH, or in CI:

curl -fsSL https://raw.githubusercontent.com/coalesce-labs/catalyst/main/setup-catalyst.sh \
  | bash -s -- --non-interactive \
      --cloud-token "$CATALYST_CLOUD_TOKEN" --cloud-account "$CATALYST_CLOUD_ACCOUNT"

-s -- is required for the piped form. Without it the flags are consumed by bash itself rather than by the script, and the install silently runs interactive — which on a host with no tty then falls back to defaults.

Prefer to read the script first, or want the prompts?

curl -O https://raw.githubusercontent.com/coalesce-labs/catalyst/main/setup-catalyst.sh
chmod +x setup-catalyst.sh
./setup-catalyst.sh                    # interactive
./setup-catalyst.sh --non-interactive  # same, no prompts

Have these ready

What	Where it goes	Format
Catalyst Cloud token	--cloud-token / CATALYST_CLOUD_TOKEN	validated with one authenticated call before anything is written — a bad token fails the install loudly
Catalyst Cloud account	--cloud-account / CATALYST_CLOUD_ACCOUNT	required whenever a token is supplied; there is deliberately no default
Linear API token	LINEAR_API_TOKEN, or ~/.linear_api_token	must be a personal key (lin_api_…). An OAuth token (lin_oauth_…) is rejected
Sentry / PostHog / Exa	prompted, or their usual env vars	all optional

Nothing above is required to get a working node — omit the cloud flags and setup behaves exactly as it always has.

This script will guide you through:

• ✅ Prerequisites check and installation (HumanLayer CLI, jq, etc.)
• ✅ Thoughts repository setup (one per org, backed up to GitHub)
• ✅ Project configuration (ticket prefix, project name)
• ✅ Integration setup (Linear, Sentry, PostHog, Exa)
• ✅ Worktree directory creation
• ✅ HumanLayer thoughts initialization and syncing

Then install the plugins:

# In Claude Code:
/plugin marketplace add coalesce-labs/catalyst
/plugin install catalyst-dev

# Restart Claude Code

Install the CLI tools — setup now does this for you. It puts catalyst-stack and the other catalyst-* commands in $HOME/.catalyst/bin, provisions plugin-source, turns on replica reads, and enrols the project. Anything it could not finish is printed at the end of the run as a deferred step, with the command that completes it and the command that verifies it — so if that list says "No steps were deferred", these are already done.

To run it by hand anyway (or to complete a deferred step):

bash ~/catalyst/plugin-source/plugins/dev/scripts/install-cli.sh
command -v catalyst-stack   # verify

Start the stack:

catalyst-stack start

This brings up broker → monitor → execution-core in dependency order. Run it once after each reboot.

You're ready! Try /research-codebase in your next session.

See the documentation site for detailed setup instructions.

Installation

Alternatively, install plugins manually via Claude Code plugin system:

# Add the marketplace repository
/plugin marketplace add coalesce-labs/catalyst

# Install the core workflow (required)
/plugin install catalyst-dev

catalyst-dev is the only required plugin. Everything else in the marketplace is optional — install only what you need. The optional roster changes over time (plugins get added, retired, or moved), so rather than enumerate it here and risk it going stale, browse it directly via .claude-plugin/marketplace.json in this repo, or the documentation site's Plugins reference.

Just want a couple of skills, not the whole plugin? Catalyst also publishes a small, hook-free portable subset — coalesce-labs/catalyst-skills — installable into any skills-CLI-compatible harness with no plugin or daemon required: Claude Code, Codex / OpenCode, or the portable-pack overview for what's in it and how pinning works.

Session-Based MCP Management

Plugins automatically load/unload MCPs when enabled/disabled:

# Enable PM ops tools for sprint planning and cycle reviews
/plugin enable catalyst-pm-ops  # Lightweight CLI-based, minimal context

# Disable when done to free context
/plugin disable catalyst-pm-ops

Why this matters: Starting with just catalyst-dev keeps your context at ~3.5k tokens, leaving more room for code and conversation.

Updating Plugins

Keep your Catalyst plugins up to date with bug fixes and new features:

# Update the marketplace to fetch latest from GitHub
claude plugin marketplace update catalyst

# Restart Claude Code to load updated plugins
# (Exit and reopen, or start a new session)

When to update:

• 🐛 Bug fixes: Patch versions (e.g., 3.0.0 → 3.0.1) - Fix issues like incorrect CLI syntax
• ✨ New features: Minor versions (e.g., 3.0.0 → 3.1.0) - New commands or capabilities
• 🔄 Breaking changes: Major versions (e.g., 3.0.0 → 4.0.0) - May require configuration updates

Important: A restart is required for plugin updates to take effect. Active sessions use the old version until you restart Claude Code.

One-command post-merge update (ff-pull + rsync into the live cache + restart):

catalyst-stack restart --hotpatch

Check your versions:

# List installed plugins and their versions
/plugin list

Need help?

• Documentation Site - Complete setup, installation, and configuration
• Claude Code Plugin Guide - Official plugin documentation

Complete Workflow

/research-codebase → /create-plan → /implement-plan → /validate-plan → /create-pr → /merge-pr

With handoffs for context persistence:

/create-handoff → /resume-handoff

Agents proactively monitor context during implementation and will prompt you to create handoffs before running out of context, creating structured handoff documents that add to persistent memory.

Learn More:

• Architecture - Three-layer system, memory model, agent teams
• Documentation Site - Complete guides and reference

Agent Teams

For complex implementations spanning multiple domains, Catalyst supports Claude Code agent teams — multiple Claude instances working in parallel on a shared codebase:

/implement-plan --team thoughts/shared/plans/my-plan.md
/oneshot --team PROJ-123

A lead agent (Opus) coordinates the work, spawning teammates (Sonnet) that each own distinct files. Each teammate can spawn its own research sub-agents, enabling two-level parallelism. See How we built our multi-agent research system for the patterns behind this approach.

Core Philosophy

Token Efficiency Through Structured Context

1. Parallel Agent Research - Multiple specialized agents research concurrently
2. Context Compression - Research compressed into structured summaries
3. Focused Planning - Planning agents work with compressed context
4. Persistent Memory - Handoffs and thoughts system preserve context across sessions

Reusability and Shared Memory

Uses the HumanLayer thoughts system for shared persistent memory across teams and projects. The research → plan → implement → validate workflow is adapted from HumanLayer's approach.

CLI-First Integration

When possible, uses CLIs instead of MCPs for token efficiency:

• Linear: Linearis CLI (1k tokens) vs Linear MCP (13k tokens) = 13x reduction
• Infrastructure research via CLIs (Sentry, GitHub)

Key Features

Large Long-Term Memory and Context

• Thoughts system for persistent memory across projects
• Structured handoff documents for context preservation
• Research artifacts saved and referenceable
• Plan documents that persist implementation context

Token Efficiency

• Parallel agents compress research before synthesis
• CLI-based tools minimize token overhead
• Focused agents for specific tasks
• Context-aware handoff prompts

Secure Configuration

• Template system prevents committing secrets
• .gitignore protection for sensitive files
• No hardcoded credentials

Requirements

Core Tools:

• Claude Code
• Git
• jq

CLI Integrations (optional but recommended):

• linearis - Linear integration (npm install -g linearis)
• gh - GitHub CLI
• sentry-cli - Error monitoring
• humanlayer - Thoughts system (install)

MCP Tools (bundled with plugins):

• Context7 - Built into catalyst-dev (~3.5k tokens)

Run the prerequisite check:

/check_prerequisites

Recurring Workflows with /loop

The built-in /loop command runs a skill or prompt on a recurring interval. Use it for monitoring and periodic tasks during active development sessions.

CI Check Monitoring (after pushing a PR)

/loop 2m gh pr checks <PR_NUMBER>

Polls every 2 minutes until checks pass or fail.

Post-Merge Deployment Monitoring

/loop 3m gh run list --branch main --limit 3 --json workflowName,status,conclusion

Monitors GitHub Actions workflow runs triggered by your merge.

Daily Context Engineering Dashboard

/loop 1d /context-daily

Refreshes the context engineering adoption dashboard once per day. Alternative to the GitHub Actions cron — useful in long-running sessions.

Backlog Grooming

/loop 1d /catalyst-pm-ops:groom-backlog

Flags orphaned, stale, and duplicate Linear tickets once per day.

Note: /loop is session-scoped (max ~3 days). For persistent scheduling, use GitHub Actions cron. /loop is best for active monitoring during development sessions.

Credits

Built on patterns from:

• HumanLayer - Thoughts system for shared persistent memory and research/plan/implement/validate workflow

Personal refinement over hundreds of hours on real projects.

Contributing

This is my personal workflow workspace, primarily built for my own development style and preferences. That said, I'm happy to:

• Discuss ideas - Open issues with workflow suggestions or improvements
• See your forks - Adapt it to your needs and share what you built
• Fix bugs - If something's broken, let me know
• Learn together - Share your workflow patterns and approaches

Important: I may not accept PRs that change core workflows or add features I don't personally use, since this is the workspace I rely on daily. But I love seeing how others adapt these patterns to their own needs!

Best approach: Fork it, make it yours, and share what you learned. That's how we all get better!

Documentation

• Documentation Site - Comprehensive guides, reference, and tutorials
• Architecture - Three-layer system and memory model
• ADRs - Architecture decision records
• Releases - Versioning and changelog conventions

Brand Assets

Catalyst ships a V2 brand kit (Ignition Chevron) under assets/brand-v2/: the mark, wordmark, lockups, favicon set, and the 1200×630 social preview card. All SVGs use stroke="currentColor" so they theme via CSS; the OG card raster (assets/brand-v2/og-card.png) bakes in the Operator Console palette.

Repo admins: to set the GitHub repository social preview, go to Settings → Social preview → Upload an image and upload assets/brand-v2/og-card.png.

License

MIT - Use it however you want!

Note on Personal Use

This is my personal workflow shared for learning and inspiration. You're welcome to use it as-is, fork it, or adapt the patterns to your own needs. Just keep in mind that it's optimized for my development style, so your mileage may vary. Some decisions are opinionated based on my preferences, and I may not accept PRs that don't align with how I work. Think of it as a starting point rather than a one-size-fits-all solution—take what works, adapt what doesn't!

---

Built by Coalesce Labs

Want to chat about workflows, contribute ideas, or share your fork? Open an issue or discussion!