Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/earendil-works/pi/llms.txt

Use this file to discover all available pages before exploring further.

Pi automatically loads context files at startup to give the model project-specific instructions, conventions, and commands. The primary context file is AGENTS.md (Pi also accepts CLAUDE.md as an alternative name).

​
How Pi loads AGENTS.md

Pi searches for AGENTS.md files in three locations and concatenates all matches:
1

Global

~/.pi/agent/AGENTS.md — loaded for every project.
2

Parent directories

Pi walks up from the current working directory, loading any AGENTS.md it finds along the way.
3

Current directory

AGENTS.md in the directory where Pi was started.
All matching files are concatenated and appended to the system prompt. This lets you layer instructions: a global file for personal preferences, repo-level files for project conventions, and a directory-level file for task-specific guidance.

​
What to put in AGENTS.md

AGENTS.md is a Markdown file. Use it for anything that helps the model work effectively in your project:
  • Project overview and architecture
  • Coding conventions and style rules
  • Common commands (build, test, lint)
  • Files or directories to avoid
  • Workflow expectations (e.g., “always run tests before committing”)
# My Project

## Architecture
This is a Next.js app using Postgres via Drizzle ORM.

## Commands
- `npm run dev` — start dev server
- `npm test` — run tests
- `npm run lint` — lint and typecheck

## Conventions
- Use `server actions` for mutations, not API routes
- Never use `any` types
- All database queries go in `lib/db/`
Pi shows which AGENTS.md files were loaded in the startup header. Use this to confirm the right files are being picked up.

​
System prompt

By default, Pi uses its built-in system prompt. You can replace or extend it.

​
Replace the system prompt

Create a SYSTEM.md file to completely replace Pi’s built-in prompt:
FileScope
.pi/SYSTEM.mdProject-level replacement
~/.pi/agent/SYSTEM.mdGlobal replacement
Replacing the system prompt removes Pi’s built-in instructions for tool use, file handling, and agent behavior. Only do this if you need full control over the prompt.

​
Append to the system prompt

Create an APPEND_SYSTEM.md file to add content after the built-in prompt without replacing it: 
<!-- APPEND_SYSTEM.md in your project root -->
Always prefer TypeScript over JavaScript.
Never modify files in the `vendor/` directory.

​
CLI flags

You can also set the system prompt from the command line: 
# Replace the system prompt
pi --system-prompt "You are a code reviewer. Focus on security."

# Append to the system prompt
pi --append-system-prompt "Always run tests before suggesting code changes."
Context files (AGENTS.md) and skills are always appended even when you replace the system prompt with --system-prompt or a SYSTEM.md file.

​
Disabling context file loading

Use --no-context-files (or -nc) to skip all AGENTS.md and CLAUDE.md discovery: 
pi --no-context-files
pi -nc
This is useful for ephemeral or one-off sessions where you want clean behavior without project-specific instructions, or when combining with --no-session for fully isolated runs: 
pi --no-context-files --no-session -p "Summarize this file" @README.md

Build docs developers (and LLMs) love

Get started for freeTalk to us