@pi-orca/profiles

Named settings snapshots with CLI switcher for switching between curated Pi configurations.

Overview

Profiles let you save and switch between named Pi settings configurations. Each profile is a snapshot of managed settings fields (packages, model defaults, etc.) stored in profiles.yaml. Switching profiles updates settings.json and reloads extensions to match.

The package also provides pi-orca-switch-profile, a standalone CLI binary that switches profile before launching Pi — no /reload needed.

Installation

The package is part of the Pi Orca monorepo and loaded as a Pi extension:

{
  "pi": {
    "extensions": ["./dist/index.js"]
  }
}

Bootstrap

On first run, the extension creates ~/.pi/agent/orca/profiles.yaml with two profiles:

| Profile | Description | |---------|-------------| | default | Snapshot of current settings.json at bootstrap time | | solo | Solo coding — tasks, models, cleanup, profiles only |

Slash Commands

/profiles (no args)

Show the current active profile (or "custom" if settings don't match any saved profile).

/profiles list

List all available profiles with descriptions.

/profiles switch <name> (alias: /profiles set)

Switch to a named profile. Updates settings.json with the profile's managed fields and triggers a reload so extensions match the new configuration. Supports tab-completion for profile names.

/profiles switch solo

/profiles save <name> [description]

Save the current settings.json as a named profile. If the profile already exists, it is overwritten.

/profiles save my-config My custom configuration

CLI: pi-orca-switch-profile

Switch profile before launching Pi so the correct extensions are loaded from the start:

# Just switch (updates settings.json and exits)
pi-orca-switch-profile solo

# Switch then launch Pi
pi-orca-switch-profile default pi --resume

How it works: The binary calls bootstrapProfiles() and switchProfile() to update settings.json before Pi starts. When Pi launches, settings already reflect the desired profile — no /reload needed.

Available via npx, npm install -g @pi-orca/profiles, or directly in the monorepo's node_modules/.bin/.

Profile Storage

Profiles are stored in YAML at ~/.pi/agent/orca/profiles.yaml:

profiles:
  default:
    description: Current Pi configuration
    settings:
      packages:
        - npm:@pi-orca/tasks
        - npm:@pi-orca/models
        # ...
  solo:
    description: "Solo coding — tasks, models, cleanup"
    settings:
      packages:
        - npm:@pi-orca/tasks
        - npm:@pi-orca/models
        - npm:@pi-orca/cleanup
        - npm:@pi-orca/profiles

Managed Fields

Profiles manage specific fields from settings.json, split into two categories:

Replace fields — fully controlled by the profile. If a field is not present in the profile, it is cleared from settings.json on switch:

• packages — list of Pi packages
• extensions — local extension overrides
• skills — local skill overrides
• prompts — local prompt overrides
• themes — local theme overrides

Merge fields — user preferences preserved across switches. Only updated if the profile explicitly specifies them:

• theme — active theme name
• defaultProvider — default AI provider
• defaultModel — default model
• defaultThinkingLevel — default thinking level

The field lists are defined in types.ts via REPLACE_FIELDS and MERGE_FIELDS.

Architecture

src/
├── cli.ts          # pi-orca-switch-profile standalone CLI binary
├── index.ts        # Extension entry point, slash command handler
├── loader.ts       # Profile I/O, switching, settings comparison, bootstrap
├── commands.ts     # Slash command implementations (show, list, switch, save)
├── types.ts        # Profile, ProfilesConfig, PiSettings, REPLACE_FIELDS, MERGE_FIELDS
└── __tests__/
    └── loader.test.ts  # Unit tests for loader functions

Dependencies

• @pi-orca/core — Path utilities, completion tree resolution, settings I/O (readPiSettings, writePiSettings, getUserOrcaDir, ensureDir)
• yaml — YAML parse/stringify for profile storage

License

MIT