Skip to content
Ultracite
Esc
↑↓navigate↵open⌘Jpreview

Pi reads AGENTS.md in every folder above you

Pi loads one context file from each folder between the filesystem root and where you start it, and AGENTS.md wins over CLAUDE.md in the same folder. Pi doesn’t ask before running tools, so when the rules tell it to run ultracite fix and check, it runs them.

Pi by EarendilChecked against Pi 1.1.0

# Ultracite Code Standards

This project uses **Ultracite**, a zero-config preset that enforces strict code quality standards through automated formatting and linting.

## Quick Reference

- **Format code**: `npx ultracite fix`
- **Check for issues**: `npx ultracite check`
- **Diagnose setup**: `npx ultracite doctor`

Oxlint + Oxfmt (the underlying engine) provides robust linting and formatting. Most issues are automatically fixable.

…
Ultracite’s rules
Where Pi looks for instructions
  1. 1~/.pi/agent/AGENTS.mdYour instructions for every project. AGENTS.override.md or CLAUDE.md there work too.
  2. 2AGENTS.override.mdIn any folder, replaces that folder’s AGENTS.md or CLAUDE.md. Other folders still load.
  3. 3AGENTS.md, root to working folderUltraciteOne per folder from the filesystem root down to where you started, outermost first.
  4. 4CLAUDE.mdUsed in a folder only when it has no AGENTS.md.

How Pi reads the rules

Pi takes your global file from ~/.pi/agent, then one context file from each folder between the filesystem root and your working folder. In each folder the first of AGENTS.override.md, AGENTS.md and CLAUDE.md wins.

One per folder
Pi loads the first of AGENTS.override.md, AGENTS.md, AGENTS.MD, CLAUDE.md and CLAUDE.MD in each folder.
Past the repo
The walk doesn’t stop at the git root, so an AGENTS.md in a parent folder applies too.
Not below
Only the working folder and its parents count. Pi doesn’t load AGENTS.md files from subfolders.
Trust
Context files load whether or not you trust the project. Trust covers .pi settings, extensions and skills.
Turn it off
--no-context-files (-nc) skips discovery for one run.
Reload
Run /reload after editing instructions; Pi picks them up without a restart.

No prompts and no hooks, just the rules

Pi has no built-in approval prompts and no hook files, so the commands in AGENTS.md run as soon as the model decides to run them. Extensions can change tool results with a tool_result handler, but Ultracite doesn’t ship one for Pi yet.

- **Format code**: `npx ultracite fix`
- **Check for issues**: `npx ultracite check`
- **Diagnose setup**: `npx ultracite doctor`
What the rules tell it to run
  1. 01Pi changes a file with its edit or write tool.
  2. 02Following AGENTS.md, the model runs npx ultracite fix or npx ultracite check with bash.
  3. 03Pi runs the command without an approval prompt.
  4. 04The model reads the output and fixes what’s left.

Worth knowing about Pi

  • The Ultracite skill asks for trust

    A project .agents/skills folder is trust-gated, so after init installs the skill, Pi asks whether to trust the project. Print, JSON and RPC modes can’t ask, so they skip it unless you pass --approve or set defaultProjectTrust to "always".

  • Extensions see every tool result

    An extension in .pi/extensions/ or ~/.pi/agent/extensions/ can register a tool_result handler that changes what the model gets back from a tool. Handlers run in load order and see each other’s changes. Ultracite doesn’t provide one yet.

  • No approvals, so isolate it

    Pi runs tools with the permissions of the account that started it and has no built-in sandbox. Its docs recommend running it inside a container, VM or sandbox, and giving it only the files and credentials the task needs.

  • The Ultracite skill

    Pi loads skills from .pi/skills/ and from .agents/skills/ in the working folder and its parents up to the repo root, so it finds the Ultracite skill init installs once you grant project trust. Run /skill:ultracite to load it yourself.

Pi questions, answered

Does Pi read AGENTS.md?
Yes. Pi loads ~/.pi/agent/AGENTS.md and one context file from each folder between the filesystem root and where you start it, preferring AGENTS.md over CLAUDE.md.
Does Pi still read my CLAUDE.md?
Only in folders without an AGENTS.md. Pi takes one file per folder, so once init writes AGENTS.md beside your CLAUDE.md, Pi reads AGENTS.md there and skips the CLAUDE.md. Move anything Pi still needs into AGENTS.md.
Does Pi support hooks?
Not as config files. Pi’s extensions are TypeScript modules that subscribe to events with pi.on(), including tool_result, which can change what a tool returns to the model. Ultracite doesn’t provide one yet.
How do I run Pi with Ultracite in CI?
pi --print "…" runs the prompt and exits, and --mode json streams events as JSONL instead. Add --approve so trust-gated project resources, the Ultracite skill among them, load without a prompt.

Sources

Keep going

Ship less slop

One command sets up your linter, formatter, editor and agents. Works with Oxlint, Biome and ESLint.