@pi-stef/catalog

Declarative package manager for the pi coding agent. Manage your skills and extensions from a single cat.yaml file, sync across machines via GitHub Gist.

Installation

pi install npm:@pi-stef/catalog

Quick Start

# 1. Authenticate with GitHub (requires gh CLI)
/ct login

# 2. Initialize catalog from installed packages (or import from a gist)
/ct init
#   or: /ct init --from-gist=<gist-id>

# 3. Sync — install missing, remove orphaned, push changes to gist
/ct sync

After ct login, your GitHub token is cached for future sync operations.

Hot-Reload

Commands that install, update, or remove packages (add, update, remove, disable, sync, pull) automatically reload extensions after a successful operation. This means new or updated tools are available immediately without restarting pi.

If the reload fails or is not available (e.g., when invoked via an LLM tool), you'll see a message asking you to restart pi for changes to take effect.

Command Reference

All commands are invoked as /ct <subcommand> inside pi, or via the shorthand /ct-<subcommand>.

| Subcommand | Alias | Description | Flags | |---|---|---|---| | sync | — | Full sync cycle: pull → reconcile → execute → push | --dry-run, --force, --no-push, --profile=<name> | | init | — | Initialize catalog from installed packages or a gist | --from-gist=<id> | | add | a | Add a package to the catalog and install it | --type=<t>, -s <t>, --scope=@pi-stef | | remove | rm | Remove a package from the catalog | --yes, --scope=@pi-stef | | toggle | — | Toggle a package's enabled state (enabled ↔ disabled) | — | | enable | — | Enable a disabled package | — | | disable | — | Disable a package and uninstall it | — | | update | up | Update packages to latest versions | --all | | push | — | Push local catalog + lock to GitHub Gist | --dry-run, --profile=<name> | | pull | — | Pull remote catalog from gist and reconcile | --dry-run, --profile=<name> | | login | — | Authenticate with GitHub via gh CLI | — | | status | — | Show catalog status with package listing | — | | diff | — | Show diff between local and remote catalog | — | | verify | — | Verify catalog integrity | — | | profiles | — | List all profiles with active indicator | — | | profile | — | Show or switch active profile | — | | reset | — | Uninstall all @pi-stef packages and delete config | --yes |

Adding Packages

# Add from a git source (name auto-derived)
/ct add git:github.com/user/repo#packages/my-skill

# Add an npm package
/ct add npm:lodash

# Add all @pi-stef packages at once
/ct add --scope=@pi-stef

Removing Packages

/ct remove my-skill
/ct remove --scope=@pi-stef

Enabling and Disabling

/ct enable my-skill      # Enable a disabled package
/ct disable my-skill     # Disable a package (uninstalls it)
/ct toggle my-skill      # Toggle enabled ↔ disabled

cat.yaml Format

The catalog is stored in cat.yaml. Example:

meta:
  pi_version: "0.70.0"
  activeProfile: default

packages:
  pair:
    source: "git:github.com/sfiorini/pi-stef#packages/pair"
    type: skill
  team:
    source: "git:github.com/sfiorini/pi-stef#packages/team"
    type: skill
  atlassian:
    source: "git:github.com/sfiorini/pi-stef#packages/atlassian"
    type: skill
    enabled: false

Package Fields

| Field | Required | Description | |---|---|---| | source | ✓ | Package source URL (npm:… or git:…) | | type | — | skill or pi-native | | profile | — | Profile name this package belongs to | | enabled | — | true (default) or false | | companions | — | Array of companion source strings to auto-install |

Companions

A package can declare required companion packages in its own package.json:

{
  "pi": {
    "companions": ["git:github.com/obra/superpowers"]
  }
}

When ct add installs such a package, it also installs each companion that isn't already installed. Companions resolve transitively (a companion may declare its own companions) up to a depth of 3, with de-duplication so each source installs at most once.

Examples

NPM source:

packages:
  lodash:
    source: "npm:lodash"

Git source:

packages:
  my-extension:
    source: "git:github.com/user/repo#packages/my-extension"
    type: pi-native

Setup Detection

Packages can include a .pi-setup.json file declaring requirements (environment variables, config files, CLI tools). After install or update, the catalog checks these requirements and warns if anything is missing.

{
  "env": ["API_TOKEN"],
  "files": ["config.json"],
  "cli": ["docker"]
}

Profiles

Profiles let you maintain different package sets for different machines or contexts (e.g., work vs. personal).

meta:
  pi_version: "0.70.0"
  activeProfile: work

packages:
  pair:
    source: "git:github.com/sfiorini/pi-stef#packages/pair"

profiles:
  work:
    packages:
      atlassian:
        source: "git:github.com/sfiorini/pi-stef#packages/atlassian"
  personal:
    packages:
      figma:
        source: "git:github.com/sfiorini/pi-stef#packages/figma"

Profile commands:

• /ct profiles — list all profiles (shows active with a marker)
• /ct profile <name> — switch active profile
• --profile=<name> flag on sync, push, pull — operate on a specific profile

The default profile always exists and uses the base packages section. Profile packages override base packages with the same key.

Configuration

File Locations

| File | Path | Purpose | |---|---|---| | Catalog | ~/.pi/sf/catalog/cat.yaml | Declarative package manifest | | Lock file | ~/.pi/sf/catalog/catalog.lock.json | Installed versions and hashes | | Gist cache | ~/.pi/sf/catalog/ | Cached gist ID for sync |

GitHub Gist Setup

Sync uses GitHub Gists for cloud storage. Prerequisites:

1. Install the GitHub CLI (gh)
2. Authenticate: gh auth login
3. Run /ct login inside pi to verify and cache your token

On first ct push or ct sync, a secret gist is created automatically.

Development

pnpm install          # Install dependencies
pnpm -F @pi-stef/catalog test    # Run tests
pnpm -F @pi-stef/catalog typecheck  # Type check

License

MIT