pi-profile

Run Pi from portable YAML agent profiles.

Profiles are declarative Pi invocations: choose a local, named, or remote YAML file; pi-profile validates it, turns keys into Pi CLI flags, and runs pi. Use --dry-run to print the generated command.

Usage

Say you want a nice personal assistant with all the "Nico Pi stack" extensions. Run this!

npx pi-agent-profile https://raw.githubusercontent.com/davidgasquez/pi-agent-profile/refs/heads/main/examples/cute-assistant.yaml --dry-run

You can install it locally with npm install -g pi-agent-profile! Then...

pi-profile ./agent.yaml
pi-profile ./agent.yaml --dry-run
pi-profile ./agent.yaml "review this repo"
pi-profile --name reviewer -p "review this repo"
pi-profile https://example.com/agent.yaml

Named profiles resolve to:

~/.pi/agent/agents/<name>.yaml

Profile format

Keys mirror Pi CLI flags without --, including flags registered by extensions.

model: openai-codex/gpt-5.5
thinking: high
print: true

tools:
  - read
  - grep
  - find
  - ls
exclude-tools:
  - ask_question

skills:
  - python-development

extensions:
  - output-schema
output-schema: response.schema.json

system-prompt: system.md
append-system-prompt: "Current date: !`date +%F`"

This becomes roughly:

pi --model openai-codex/gpt-5.5 --thinking high --print \
  --no-skills --skill ~/.pi/agent/skills/python-development \
  --no-extensions --extension ~/.pi/agent/extensions/output-schema.ts \
  --output-schema /absolute/path/response.schema.json \
  --system-prompt "$(cat system.md)" \
  --append-system-prompt "Current date: 2026-05-27" \
  --exclude-tools ask_question

Defaults and isolation

Omitted keys usually keep Pi defaults. For isolation, these default to disabled unless explicitly set:

prompt-templates: false
themes: false
context-files: false

Set any of them to true to opt back into Pi discovery.

Boolean false maps to Pi's --no-* flags where supported, for example:

tools: false # --no-tools
skills: false # --no-skills
extensions: false # --no-extensions

When skills or extensions is a list, discovery for that resource is disabled and only the listed entries are loaded.

Paths and resources

• Bare skills resolve to ~/.pi/agent/skills/<name>.
• Bare extensions resolve to ~/.pi/agent/extensions/<name>, <name>.ts, or <name>/index.ts.
• Existing relative file paths are resolved relative to the profile.
• For remote profiles, relative Markdown prompt files and file-like flag values such as JSON schemas are resolved relative to the profile URL and downloaded to temp files.
• Remote extension, skill, prompt-template, and theme URLs are downloaded to temp files and passed to Pi.
• Package refs like npm:pi-web-providers and git:github.com/user/repo pass through unchanged.

Prompts

Prefer Markdown files for substantial prompts:

system-prompt: cute-assistant.system.md
append-system-prompt: "Current date: !`date +%F`"

*.md and *.mdx prompt values are read relative to the profile. Inline !backtick`` commands run at invocation time and insert stdout.

See examples/cute-assistant.yaml for a complete example.