pi-match-rules

A pi extension that loads Markdown rules from global and project-local .claude/rules directories and injects the relevant rules into pi's system prompt.

Install

This repository is a pi package. Install it from this checkout for all pi sessions:

pi install ./

Or from npm once published:

pi install npm:pi-match-rules

Use this checkout directly without installing (good while developing):

pi -e ./index.ts

Rule format

Rules are Markdown files with YAML-style frontmatter. Supported matching keys:

• alwaysApply: true
• pattern / patterns
• path / paths
• glob / globs

Example:

---
globs:
  - "**/*.py"
  - "**/pyproject.toml"
---

# Python Rules

Use strict typing and pytest.

Rules with alwaysApply: true — or no frontmatter at all — are injected every turn. Conditional rules are injected when the user prompt mentions a path matching one of the frontmatter patterns. A rule that has frontmatter but no alwaysApply and no patterns is inactive.

Rules are loaded from both:

• Global: ~/.claude/rules/**/*.md by default
• Local: <project>/.claude/rules/**/*.md

If a global and local rule share the same relative path under their rules directory, the local rule wins and the global one is not loaded. Only exact relative-path collisions override; python/api.md, ts/api.md, and api.md are all different rule names.

Tool

The extension registers load_claude_rules, which the agent can call with file paths discovered during the task. It returns the matching rule contents plus alwaysApply rules by default. Tool output is truncated to 50KB or 2000 lines.

Commands

• /claude-rules — show how many rules are loaded.
• /claude-rules reload — reload files from disk.
• /claude-rules <path> [path...] — show the rules matching one or more paths.

Configuration

Set PI_CLAUDE_RULES_DIR to use a different global rules directory:

PI_CLAUDE_RULES_DIR=~/my-rules pi -e ./index.ts

Glob support

The matcher supports *, **, ?, brace extensions such as *.{ts,tsx}, and character classes such as *[Tt]able*.tsx.