pi-profile

A pi extension for instant identity switching — swap model, skills, subagents, and system prompt in the same session, no restart needed.

/profile researcher          # switch to the researcher identity
/profile default             # back to default
pi --profile researcher      # start directly in a profile

Install

pi install npm:pi-profile

Example profiles (default, researcher) ship in the repo's profiles/ directory — copy them to ~/.pi/profiles/ to start, or build your own with /profile create.

Quick start

# Use the researcher profile (ships as example)
pi --profile researcher

# Inside an interactive session
/profile researcher

# List all profiles
/profile list

How it works

pi-profile hooks into pi's extension API to switch runtime identity:

| Layer | Mechanism | Effect | |-------|-----------|--------| | Skills | before_agent_start + tool_call | 3-layer hard block: skills outside profile are invisible to the LLM | | Subagents | Agent .md file sync | Profile-defined team members available for delegation | | Prompt | before_agent_start | Profile's system prompt injected each turn (append mode) | | Model | pi.setModel() | Different profiles use different models | | Autocomplete | addAutocompleteProvider | / only shows profile's skills and templates |

Identity, not security. Profile controls who the AI is — not what tools it can use or what commands are dangerous. Tool access and security policies are handled by dedicated extensions like pi-permission-suite.

Profile files

Stored as ~/.pi/profiles/<name>.json:

{
  "name": "researcher",
  "label": "🔬 Deep Researcher",
  "description": "Deep research mode with web search focus",

  "systemPrompt": "你是一个严谨的研究助手。\n\n## 准则\n1. 每次回答必须附上来源链接\n2. 优先使用 web_search 验证事实\n3. 交叉验证多个来源后再得出结论\n4. 用结构化格式输出（列表、表格、摘要）\n5. 遇到不确定的，明确说明",

  "model": {
    "provider": "opencode-go",
    "model": "kimi-k2.6",
    "thinkingLevel": "high"
  },

  "skills": ["learn", "wiki-read", "wiki-write"],

  "sessionName": "🔬 Research"
}

Profile interface

| Field | Type | Description | |-------|------|-------------| | name | string | Unique ID (lowercase, no spaces) | | label | string? | Display label (emojis OK) | | description | string? | One-line summary shown in profile list | | systemPrompt | string? | Appended to Pi's default system prompt each turn | | model | {provider, model, thinkingLevel?} | Optional fixed model binding | | skills | string[]? | Skills visible to LLM (undefined = all skills visible) | | prompts | string[]? | Prompt templates visible in autocomplete | | subagents | Record<string, Subagent> | Team members synced to Pi's agent system | | sessionName | string? | Auto-session label when using this profile |

Skill hard blocking (3 layers)

When skills is set, non-listed skills are completely invisible to the LLM:

| Layer | What | How | |-------|------|-----| | 1 | System prompt | <available_skills> XML filtered — LLM never sees them listed | | 2 | Read interception | LLM calling read() on a non-profile SKILL.md is blocked | | 3 | Autocomplete | /skill:<name> doesn't appear in auto-complete |

This means the LLM cannot know about, discover, or use skills outside the profile's scope. Skills still load at startup — profile controls visibility, not availability.

Commands

| Command | Description | |---------|-------------| | /profile | Show current profile + available list | | /profile <name> | Switch profile | | /profile list | List all profiles | | /profile show <name> | Show profile JSON | | /profile create | Interactive wizard (AI-guided or manual) | | /profile rm <name> | Delete profile |

CLI

pi --profile <name>       # Start with profile
PI_PROFILE=<name> pi      # Via environment variable