Skip to main content
The config directory is pi’s agent directory for the session, like ~/.pi/agent. It is config/, or UBER_CONFIG_DIR: The repository’s own AGENTS.md and skills, in .pi/skills or .agents/skills, are read from the workspace. Its .pi settings and extensions are not. Pi installs packages into the config directory, so it must be writable. To install them ahead of time, run:

​
Context

AGENTS.md holds guidance for every repository, added to the prompt before the repository’s own:

​
Prompt templates

Each file in prompts/ is a task template, named after the file. A task such as /review security expands prompts/review.md on the agent:

​
Extensions

Extensions work as in pi. A tool an extension registers runs as a recorded step under policy. A tool marked readOnlyHint is safe_to_retry; any other runs at_most_once. Hooks run again on each replay, so wrap side effects in step(). ctx.ui calls do nothing. A replay returns a tool’s recorded result without running it. Entries the tool appended with pi.appendEntry() are appended again, and session_start fires again before the first tool that runs, so an extension that rebuilds its state from the session on session_start, as pi recommends, keeps it. State held only in memory is lost when a turn resumes, such as after an approval. Extensions load for every session unless settings.json turns them off, as pi config does. A session can turn those back on by name: a package’s name, or an extension’s file name without its extension. A turn’s extensions lists them, and the session keeps the list until a turn sends another:

​
Environment