fitout

Fitout

Context-aware plugin manager for Claude Code.

The Problem

Managing Claude Code plugins across projects is painful:

• Config files look correct but don't reflect what's actually installed
• This mismatch leads to broken sessions and missing capabilities
• Manually syncing plugins across projects is tedious and error-prone

The Solution

Fitout ensures your actual runtime state matches your declared configuration.

• Declare desired plugins in .claude/fitout.toml
• Run fitout status to see the diff
• Run fitout install to sync

Installation

# Install globally
npm install -g fitout

# Set up Claude integration
fitout init

This adds a SessionStart hook to Claude Code that automatically installs missing plugins when you start a session.

Non-interactive setup

fitout init --yes        # Use defaults (creates default profile)
fitout init --hook-only  # Only add hook, no profile

Requires Claude Code CLI to be installed.

Quick Start

Create .claude/fitout.toml in your project:

plugins = [
  "superpowers@superpowers-marketplace",
  "ci-cd-tools@pickled-claude-plugins",
]

Check status:

fitout status

Output:

Context: /path/to/project

✗ superpowers@superpowers-marketplace (missing)
✗ ci-cd-tools@pickled-claude-plugins (missing)

0 present, 2 missing

Install missing plugins:

fitout install

Commands

fitout status

Shows the diff between desired and installed plugins.

• ✓ - Plugin is installed
• ✗ - Plugin is missing
• ? - Plugin is installed but not in config

Exit code is 1 if any plugins are missing, 0 otherwise.

fitout install

Installs missing plugins to sync with config.

fitout install           # Install missing plugins
fitout install --dry-run # Preview what would be installed

fitout profiles

Lists available profiles with descriptions and plugin counts.

fitout profiles          # Table output
fitout profiles --json   # JSON for scripting

Profiles

Share plugin sets across projects using profiles.

User Profiles

Create profiles at ~/.config/fitout/profiles/:

# ~/.config/fitout/profiles/default.toml
# Auto-included in every project (silent if missing)
description = "Baseline plugins for all projects"

plugins = [
  "superpowers@superpowers-marketplace",
]

# ~/.config/fitout/profiles/backend.toml
description = "Backend services and APIs"

plugins = [
  "database-tools@some-registry",
  "api-helpers@some-registry",
]

Using Profiles

Reference profiles in your project config:

# .claude/fitout.toml
profiles = ["backend"]
plugins = [
  "project-specific@registry",
]

Plugins merge additively. The default profile auto-includes if present.

Provenance

Status output shows where each plugin comes from:

Context: /path/to/project

✓ superpowers@superpowers-marketplace (from: default)
✓ database-tools@some-registry (from: backend)
✓ project-specific@registry

3 present

Configuration Reference

Project Config (.claude/fitout.toml)

# Optional: explicit profiles to include
profiles = ["backend", "testing"]

# Required: plugins for this project
plugins = [
  "plugin-name@registry",
]

Profile Config (~/.config/fitout/profiles/<name>.toml)

# Optional: human-readable description (shown by fitout profiles)
description = "What this profile provides"

# Plugins provided by this profile
plugins = [
  "plugin-name@registry",
]

Development

npm install          # Install dependencies
npm test             # Run tests
npm run dev -- status # Run in dev mode
npm run build        # Build to dist/

License

MIT