pi-capitals-context

Auto-discovers ALL_CAPS files and folders in your project and injects them into pi's system prompt as context. Toggle individual files, preview content, search, sort — all from a /caps overlay.

Install

pi install npm:pi-capitals-context

What it loads

| Source | Example | Notes | |--------|---------|-------| | Root CAPS files | STATUS.md, DESIGN.md | Individually toggleable | | Root CAPS folders | RULES/, CONTEXT/ | Each file inside is individually toggleable | | Global folder | ~/.pi/CAPS/ | Loaded in every project | | Subdirectories | src/GUIDE.md | Auto-loaded when you reference that folder |

Skips noise by default: AGENTS.md, CLAUDE.md, LICENSE, LICENSE.md, README.md, CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md. Per-project override via /caps-advance skip add/remove or .pi/caps-config.json. See Configuration.

Supported file types

Inside CAPS folders: .md, .txt, .yaml, .yml, .json, .toml

Root-level CAPS files: .md only (e.g. STATUS.md, DESIGN.md)

Project structure example

my-project/
├── STATUS.md               ← loaded individually
├── DESIGN.md               ← loaded individually
├── RULES/                  ← CAPS folder — each file toggleable separately
│   ├── typescript.md
│   ├── git-conventions.md
│   └── code-review.md
├── CONTEXT/                ← CAPS folder — supports mixed file types
│   ├── glossary.md
│   ├── config.yaml
│   └── schema.json
├── src/
│   └── GUIDE.md            ← auto-loaded when you reference src/
└── api/
    └── SPEC.md             ← auto-loaded when you reference api/

Global context

Files in ~/.pi/CAPS/ are loaded in every project — useful for personal preferences, identity, or cross-project rules:

~/.pi/CAPS/
├── IDENTITY.md       ← who you are, role, language preferences
├── WORK_STYLE.md     ← how you like to work with AI
└── STANDARDS/
    ├── writing.md
    └── code.md

/caps overlay

Type /caps to open the context manager. Features:

Folder collapse / expand

Folders start collapsed. Navigate to a folder row and press space to expand it and see individual files. Press space again on the expanded header to toggle all files at once. Press ← to collapse.

  ▶ ◑ RULES/ (3 files)        ← collapsed, space to expand
  ☑ STATUS.md · 45 tokens

  ▼ ◑ RULES/ (3 files)        ← expanded, space toggles all, ← collapses
    ☑ typescript.md · 32 tokens
    ☑ git-conventions.md · 28 tokens
    ☐ code-review.md · 41 tokens
  ☑ STATUS.md · 45 tokens

Sort

Navigate to the ⇅ Sort: row and press space to cycle through:

• default — discovery order
• a–z — alphabetical
• tokens↓ — heaviest files first

Search / filter

Start typing anywhere to filter the list. The list narrows live. Press ⌫ to erase. Press Esc to clear the filter.

Preview panel

When your terminal is wide enough (≥74 cols), hovering a file opens a side panel showing its content with line numbers. Long files show top lines, a ── N lines ── separator, and bottom lines.

Hovering a folder header shows a summary of all files inside with their token counts.

Navigation

| Key | Action | |-----|--------| | ↑↓ | Navigate | | space | Expand/collapse folder · toggle file · cycle sort | | ← | Collapse expanded folder | | esc | Clear filter (if active) · close overlay | | Type anything | Filter list | | ⌫ | Erase filter character |

File watcher

While pi is running, if you edit a CAPS file it detects the change and shows:

⚠  STATUS.md changed · restart to reload

Content isn't updated mid-session to avoid corrupting context — restart pi to pick up changes.

Token counts

Token estimates use a word-based heuristic (more accurate than character counting). Each file shows its cost, and the overlay shows a running total.

[CAPS Context]
  STATUS.md · 45 tokens
  RULES/typescript.md · 32 tokens
  RULES/git-conventions.md · 28 tokens
  total: 105 tokens
  /caps to toggle

State persistence

Toggle choices are saved per-project in .pi/caps-context-state.json using atomic writes (safe against crashes). The file is per-project and not version-controlled.

Filename rules

• Root files: ALL_CAPS.md — uppercase letters, numbers, underscores only
• Folders: ALL_CAPS/ — same naming, any supported file type inside
• Valid: STATUS.md, MY_RULES.md, STYLE_GUIDE_V2.md
• Valid folders: RULES/, MEMORY/, API/, CONTEXT/

Single file ideas

| File | Use for | |------|---------| | STATUS.md | Current sprint, blockers, recent decisions | | DESIGN.md | Architecture, tech stack, system design | | WORKFLOW.md | Git conventions, PR process, deployment | | STYLE.md | Code style, tone, formatting rules | | CONSTRAINTS.md | Limitations, budgets, non-negotiables | | TODO.md | Outstanding tasks and priorities |

Folder ideas

| Folder | Use for | |--------|---------| | RULES/ | Coding standards, review checklist | | MEMORY/ | Past decisions, lessons learned | | CONTEXT/ | Domain knowledge, glossary, onboarding | | API/ | Endpoint docs, schemas, auth flows | | TEMPLATES/ | Reusable patterns, boilerplate |

Keybinding

To bind a custom shortcut to /caps, add to ~/.pi/agent/keybindings.json:

{
  "bindings": [
    { "key": "ctrl+shift+c", "command": "caps" }
  ]
}

Commands

| Command | What it does | |---|---| | /caps | Toggle overlay — root, subdir, and global CAPS files. Daily driver. | | /caps-profile | Overlay picker for saved toggle profiles. Top row is + Create new profile — picking it chains into the /caps file picker, then a name-input overlay (Enter saves, Esc discards & restores toggles). Existing profile rows: Enter loads, e edits (loads → /caps → saves back), r renames (name-input pre-filled), d twice deletes, Esc quits. Project-scoped; Global CAPS toggles untouched. | | /caps-settings | Settings Hub overlay — rows for Skip list, Prompt preview, Diagnose / Doctor (all active); Configuration (stub). Enter opens a row, Esc quits. The primary entry point for non-daily-driver actions. | | /caps-advance skip <list\|add\|remove\|reset> | Typed scripting fallback for skip list. Overlay path: /caps-settings → Skip list. | | /caps-prompt | Typed scripting fallback for prompt preview. --copy pipes to clipboard, --diff shows line-diff vs previous turn. Overlay path: /caps-settings → Prompt preview (with c copy / p diff keys). | | /caps-doctor | Typed scripting fallback for diagnostics. --verbose shows every entry in cwd with classification. Overlay path: /caps-settings → Diagnose / Doctor (with v verbose key). |

Profiles (typed shortcuts)

• /caps-profile save <name> — capture current toggles into a named profile
• /caps-profile load <name> [--dry-run] — apply profile (or preview with --dry-run)
• /caps-profile rename <old> <new> — rename a profile
• /caps-profile list — print profile names (text fallback)

Profiles persist to .pi/caps-profiles.json (atomic write). Loading applies immediately and persists project state — no pi restart needed.

Each command supports help (e.g. /caps-doctor help) for inline usage.

Configuration

Defaults work for most projects. Override per-project at .pi/caps-config.json, or globally at ~/.pi/caps-config.json. Project wins over global wins over built-in defaults.

Example — re-include LICENSE.md and README.md as context (research repo where license terms matter):

{
  "skipFiles": ["AGENTS.md", "CLAUDE.md"]
}

Full schema (all fields optional):

| Field | Type | Default | |---|---|---| | skipFiles | string[] | ["AGENTS.md","CLAUDE.md","LICENSE","LICENSE.md","README.md","CHANGELOG.md","CONTRIBUTING.md","CODE_OF_CONDUCT.md","SECURITY.md"] | | skipDirs | string[] | ["AGENTS","CLAUDE","NODE_MODULES","node_modules",".git",".pi"] | | capsFilePattern | string (regex) | "^[A-Z][A-Z0-9_]*\\.md$" | | capsDirPattern | string (regex) | "^[A-Z][A-Z0-9_]*$" | | textExtensions | string[] | [".md",".txt",".yaml",".yml",".json",".toml"] | | maxFileSizeBytes | number | 102400 (100KB) | | maxRecursionDepth | number | 6 | | maxSubdirFiles | number | 20 |

Invalid values (e.g. unparseable regex, negative numbers) fall back to defaults silently — the tool stays loadable.

Changes take effect on pi restart (config is read at session_start).

Troubleshooting

When a file you expected to load isn't appearing, run /caps-doctor. It tells you:

• Whether the project directory was scanned correctly
• Which entries were skipped and why (regex mismatch, in skip list, too large, symlink)
• Where the state file lives and whether it loaded
• Whether any config override is active
• Last injection size + tokens

/caps-doctor --verbose lists every file in the cwd with ✓/✗ classification.

Common cases:

• "My file is notes.md but doesn't load." → filename must be ALL-CAPS (NOTES.md).
• "LICENSE.md shouldn't be excluded for my project." → /caps-advance skip remove LICENSE.md, restart pi.
• "Tool seems to ignore my edit." → file watcher only notifies; you must restart pi to reload content.
• "/caps-prompt shows nothing." → no files enabled or no CAPS files exist. Run /caps-doctor.