pi-context-filter 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HazAT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# Context Filter
+
+A pi extension that gives you `.gitignore`-style control over which context files, agent instructions, and skills are included in the system prompt.
+
+## Why?
+
+Pi automatically loads `AGENTS.md` / `CLAUDE.md` files from your home directory, ancestor directories, and the current project. It also loads all discovered skills into the prompt. Sometimes you want to override this — exclude a parent project's instructions when working in a subfolder, skip the global `AGENTS.md`, or inject your own context files.
+
+## Setup
+
+Place a `.context` file in your project's `.pi/` directory:
+
+```
+your-project/
+├── .pi/
+│   └── .context
+└── ...
+```
+
+Pi reads this file on session start. Use `/reload` to pick up changes without restarting.
+
+## Syntax
+
+```bash
+# Lines starting with # are comments
+# Blank lines are ignored
+
+# Exclude files with ! (supports globs)
+!~/.pi/agent/AGENTS.md
+
+# Include files with + (resolved relative to project root)
++.pi/MYCONTEXT.md
+```
+
+### Exclusions (`!`)
+
+Exclude `AGENTS.md` / `CLAUDE.md` sections and skill entries from the system prompt. Patterns are matched against absolute file paths using [picomatch](https://github.com/micromatch/picomatch) glob syntax.
+
+```bash
+# Exact path (~ expands to home directory)
+!~/.pi/agent/AGENTS.md
+
+# All AGENTS.md files from any ancestor directory
+!**/AGENTS.md
+
+# A specific skill
+!**/skills/brainstorm/SKILL.md
+
+# All skills under a directory
+!**/skills/**
+```
+
+### Inclusions (`+`)
+
+Add arbitrary files to the system prompt. Paths are resolved relative to the project root. Files are read fresh on every prompt, so edits are picked up immediately.
+
+```bash
+# Add a custom context file
++.pi/MYCONTEXT.md
+
+# Absolute paths work too
++~/shared-context/team-guidelines.md
+```
+
+## Examples
+
+**Use only the local project's AGENTS.md, ignore everything else:**
+
+```bash
+# .pi/.context
+!~/.pi/agent/AGENTS.md
+!../**/AGENTS.md
+```
+
+**Swap in your own context file:**
+
+```bash
+# .pi/.context
+!**/AGENTS.md
++.pi/my-instructions.md
+```
+
+**Keep everything but drop a noisy skill:**
+
+```bash
+# .pi/.context
+!**/skills/brainstorm/SKILL.md
+```
+
+## How It Works
+
+The extension hooks into pi's `before_agent_start` event to modify the system prompt before each LLM call:
+
+1. **Exclusions** — Strips `## /path/to/AGENTS.md` sections from the Project Context block and removes matching `<skill>` entries from the available skills list.
+2. **Inclusions** — Reads the specified files and appends them to the Project Context section.
+
+On startup, a widget above the editor shows all active rules (auto-hides after 15 seconds), and a persistent footer status displays the filter summary (e.g., `[.context] ✕ 5 excluded`).
+
+Note: Pi's own `[Context]` and `[Skills]` startup display still shows all discovered files — that's pi's internal display and can't be changed by extensions. The widget and footer make it clear what's actually being filtered from the prompt.
+
+## Limitations
+
+- **Extensions cannot be filtered.** Extension loading happens before any extension code runs, so this tool can only control what appears in the *system prompt* (AGENTS.md content and skill listings).
+- **Format-dependent.** The extension parses the system prompt structure that pi generates. If pi significantly changes its prompt format in the future, the filtering may need updating.

package/index.ts

@@ -0,0 +1,229 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { homedir } from "node:os";
+import picomatch from "picomatch";
+
+interface ContextRules {
+  exclusionPatterns: string[]; // original patterns for display
+  exclusions: picomatch.Matcher[];
+  inclusions: string[]; // resolved absolute paths
+  inclusionPatterns: string[]; // original patterns for display
+}
+
+function expandTilde(p: string): string {
+  if (p === "~") return homedir();
+  if (p.startsWith("~/")) return join(homedir(), p.slice(2));
+  return p;
+}
+
+function parseContextFile(filePath: string, cwd: string): ContextRules {
+  const rules: ContextRules = {
+    exclusionPatterns: [],
+    exclusions: [],
+    inclusions: [],
+    inclusionPatterns: [],
+  };
+
+  if (!existsSync(filePath)) return rules;
+
+  const content = readFileSync(filePath, "utf-8");
+  for (const rawLine of content.split("\n")) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+
+    if (line.startsWith("!")) {
+      const raw = line.slice(1).trim();
+      const pattern = expandTilde(raw);
+      rules.exclusionPatterns.push(raw);
+      rules.exclusions.push(picomatch(pattern, { dot: true }));
+    } else if (line.startsWith("+")) {
+      const raw = line.slice(1).trim();
+      const rawPath = expandTilde(raw);
+      rules.inclusionPatterns.push(raw);
+      rules.inclusions.push(resolve(cwd, rawPath));
+    }
+  }
+
+  return rules;
+}
+
+function isExcluded(filePath: string, matchers: picomatch.Matcher[]): boolean {
+  return matchers.some((m) => m(filePath));
+}
+
+/**
+ * Remove ## path sections from the "# Project Context" area of the system prompt.
+ * Sections look like: ## /absolute/path/to/AGENTS.md\n\n<content>\n\n
+ */
+function filterContextSections(prompt: string, matchers: picomatch.Matcher[]): string {
+  if (matchers.length === 0) return prompt;
+
+  // Match sections: ## <path>\n\n<content up to next ## or end of Project Context>
+  // The Project Context block starts with "# Project Context"
+  const projectCtxStart = prompt.indexOf("# Project Context");
+  if (projectCtxStart === -1) return prompt;
+
+  // Find where Project Context ends (next top-level heading or skills section)
+  const afterCtx = prompt.indexOf("\n\nThe following skills", projectCtxStart);
+  const afterDate = prompt.indexOf("\nCurrent date and time:", projectCtxStart);
+
+  let projectCtxEnd: number;
+  if (afterCtx !== -1) {
+    projectCtxEnd = afterCtx;
+  } else if (afterDate !== -1) {
+    projectCtxEnd = afterDate;
+  } else {
+    projectCtxEnd = prompt.length;
+  }
+
+  const before = prompt.slice(0, projectCtxStart);
+  const contextBlock = prompt.slice(projectCtxStart, projectCtxEnd);
+  const after = prompt.slice(projectCtxEnd);
+
+  // Split context block into sections by ## /path headers only.
+  // AGENTS.md content contains its own ## headings, so we must only match
+  // headers that look like file paths (start with /).
+  const sectionRegex = /^## (\/[^\n]+)$/gm;
+  const sections: { path: string; start: number; end: number }[] = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = sectionRegex.exec(contextBlock)) !== null) {
+    if (sections.length > 0) {
+      sections[sections.length - 1].end = match.index;
+    }
+    sections.push({ path: match[1].trim(), start: match.index, end: contextBlock.length });
+  }
+
+  // Build filtered context block
+  let filtered = contextBlock;
+  // Process in reverse to preserve indices
+  for (let i = sections.length - 1; i >= 0; i--) {
+    const section = sections[i];
+    if (isExcluded(section.path, matchers)) {
+      filtered = filtered.slice(0, section.start) + filtered.slice(section.end);
+    }
+  }
+
+  // If all sections were removed, remove the entire Project Context header too
+  const hasAnySections = /^## /m.test(filtered);
+  if (!hasAnySections) {
+    return before.trimEnd() + after;
+  }
+
+  return before + filtered + after;
+}
+
+/**
+ * Remove <skill> blocks whose <location> matches an exclusion pattern.
+ */
+function filterSkillBlocks(prompt: string, matchers: picomatch.Matcher[]): string {
+  if (matchers.length === 0) return prompt;
+
+  return prompt.replace(
+    /  <skill>\n(?:.*\n)*?  <\/skill>/g,
+    (block) => {
+      const locMatch = block.match(/<location>([^<]+)<\/location>/);
+      if (locMatch && isExcluded(locMatch[1], matchers)) {
+        return "";
+      }
+      return block;
+    }
+  );
+}
+
+/**
+ * Append included files to the system prompt in the Project Context section.
+ */
+function appendInclusions(
+  prompt: string,
+  inclusions: string[],
+  notify: (msg: string) => void
+): string {
+  if (inclusions.length === 0) return prompt;
+
+  let additions = "";
+  for (const filePath of inclusions) {
+    if (!existsSync(filePath)) {
+      notify(`context-filter: missing inclusion file: ${filePath}`);
+      continue;
+    }
+    try {
+      const content = readFileSync(filePath, "utf-8");
+      additions += `## ${filePath}\n\n${content}\n\n`;
+    } catch (e) {
+      notify(`context-filter: failed to read ${filePath}: ${e}`);
+    }
+  }
+
+  if (!additions) return prompt;
+
+  // Insert before skills section or date line
+  const skillsIdx = prompt.indexOf("\n\nThe following skills");
+  const dateIdx = prompt.indexOf("\nCurrent date and time:");
+  const insertIdx = skillsIdx !== -1 ? skillsIdx : dateIdx !== -1 ? dateIdx : prompt.length;
+
+  // Ensure there's a Project Context section
+  const hasProjectCtx = prompt.includes("# Project Context");
+  if (!hasProjectCtx) {
+    additions = "\n\n# Project Context\n\nProject-specific instructions and guidelines:\n\n" + additions;
+  }
+
+  return prompt.slice(0, insertIdx) + additions + prompt.slice(insertIdx);
+}
+
+export default function (pi: ExtensionAPI) {
+  let rules: ContextRules = { exclusions: [], inclusions: [] };
+  let cwd = process.cwd();
+
+  pi.on("session_start", async (_event, ctx) => {
+    cwd = ctx.cwd;
+    const contextPath = join(cwd, ".pi", ".context");
+    rules = parseContextFile(contextPath, cwd);
+
+    if (!ctx.hasUI) return;
+    if (rules.exclusions.length === 0 && rules.inclusions.length === 0) return;
+
+    // Show summary in footer status
+    const parts: string[] = [];
+    if (rules.exclusionPatterns.length > 0) {
+      parts.push(`✕ ${rules.exclusionPatterns.length} excluded`);
+    }
+    if (rules.inclusionPatterns.length > 0) {
+      parts.push(`✓ ${rules.inclusionPatterns.length} included`);
+    }
+    ctx.ui.setStatus("context-filter", `[.context] ${parts.join(", ")}`);
+
+    // Show detailed widget above editor
+    const lines: string[] = ["[Context Filter]"];
+    for (const p of rules.exclusionPatterns) {
+      lines.push(`  ✕ ${p}`);
+    }
+    for (const p of rules.inclusionPatterns) {
+      lines.push(`  ✓ ${p}`);
+    }
+    ctx.ui.setWidget("context-filter", lines);
+
+    // Auto-hide widget after 15 seconds, keep status
+    setTimeout(() => {
+      ctx.ui.setWidget("context-filter", undefined);
+    }, 15_000);
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    if (rules.exclusions.length === 0 && rules.inclusions.length === 0) return;
+
+    let prompt = event.systemPrompt;
+
+    // Apply exclusions
+    prompt = filterContextSections(prompt, rules.exclusions);
+    prompt = filterSkillBlocks(prompt, rules.exclusions);
+
+    // Apply inclusions
+    prompt = appendInclusions(prompt, rules.inclusions, (msg) => {
+      if (ctx.hasUI) ctx.ui.notify(msg, "warning");
+    });
+
+    return { systemPrompt: prompt };
+  });
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "pi-context-filter",
+  "version": "1.0.0",
+  "description": "A pi extension that provides .gitignore-style control over which context files and skills appear in the system prompt",
+  "keywords": ["pi-package"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HazAT/pi-context-filter"
+  },
+  "license": "MIT",
+  "pi": {
+    "extensions": ["./index.ts"]
+  },
+  "dependencies": {
+    "picomatch": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/picomatch": "^3.0.0"
+  }
+}