# Agent Profile

The agent profile lets you shape how HyperDesk agents behave without rewriting the same instruction in every prompt.

Open it from:

- **Session > Agent Profile…**
- On macOS, the app menu also includes **Agent Profile…**
- Keyboard shortcut: **Cmd/Ctrl+Shift+P**

## Profile scopes

HyperDesk supports two scopes:

- **Project profile**: stored in the current workspace under `.pi/hyper-desk/`.
- **Global profile**: stored under your user Pi agent profile area and reused across projects.

Project profiles are best for repo-specific conventions. Global profiles are best for stable personal preferences.

## Profile files

The profile editor manages three Markdown files:

- `identity.md`: the agent's role, tone, boundaries, and operating style.
- `user.md`: facts and preferences about the user.
- `soul.md`: higher-level principles for how the agent should think and collaborate.

## Good profile guidance

Keep profiles short, explicit, and durable. Put temporary task instructions in chat, not the profile.

Examples:

- “Prefer concise status updates with commands and validation results.”
- “Always use pull requests for changes to protected branches.”
- “Do not expose private keys or secrets.”
- “When changing UI, preserve the current visual language unless asked otherwise.”

## For agents

Before answering questions about user preferences or project process, check whether an agent profile exists. Treat profile content as durable context, but do not invent missing preferences.
