@mrclrchtr/supi-claude-md 0.1.0

package/src/claude-md.ts

@@ -0,0 +1,163 @@
+// supi-claude-md — subdirectory context injection for pi.
+//
+// Subdirectory discovery: inject CLAUDE.md/AGENTS.md from subdirectories
+// below cwd when the agent accesses files there (via tool_result augmentation).
+// Root/ancestor context files are owned by pi's native system prompt and are
+// never re-injected by this extension.
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+  BeforeAgentStartEvent,
+  ExtensionAPI,
+  ExtensionContext,
+  SessionCompactEvent,
+  SessionStartEvent,
+  TurnEndEvent,
+} from "@earendil-works/pi-coding-agent";
+import { loadClaudeMdConfig } from "./config.ts";
+import {
+  extractPathFromToolEvent,
+  filterAlreadyLoaded,
+  findSubdirContextFiles,
+} from "./discovery.ts";
+import { registerClaudeMdSettings } from "./settings-registration.ts";
+import { type ClaudeMdState, createInitialState, reconstructState } from "./state.ts";
+import type { ContextUsage, InjectionCheckOptions } from "./subdirectory.ts";
+import { formatSubdirContext, shouldInjectSubdir } from "./subdirectory.ts";
+
+const baseDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+export default function claudeMdExtension(pi: ExtensionAPI) {
+  registerClaudeMdSettings();
+  const state: ClaudeMdState = createInitialState();
+
+  // ── Session lifecycle ──────────────────────────────────────
+
+  pi.on("session_start", async (_event: SessionStartEvent, ctx: ExtensionContext) => {
+    Object.assign(state, createInitialState());
+
+    try {
+      const branch = ctx.sessionManager.getBranch();
+
+      if (branch.length > 0) {
+        const reconstructed = reconstructState(branch);
+        state.completedTurns = reconstructed.completedTurns;
+        state.injectedDirs = reconstructed.injectedDirs;
+      }
+    } catch {
+      // Reconstruction failed — start fresh
+    }
+  });
+
+  // ── Turn tracking ──────────────────────────────────────────
+
+  pi.on("turn_end", async (event: TurnEndEvent, _ctx: ExtensionContext) => {
+    const msg = event.message as { stopReason?: string };
+    if (msg?.stopReason === "stop") {
+      state.completedTurns++;
+    }
+  });
+
+  // ── Compaction ─────────────────────────────────────────────
+
+  pi.on("session_compact", async (_event: SessionCompactEvent, _ctx: ExtensionContext) => {
+    state.injectedDirs.clear();
+  });
+
+  // ── Native context path capture (before_agent_start) ───────
+
+  pi.on("before_agent_start", async (event: BeforeAgentStartEvent, _ctx: ExtensionContext) => {
+    const eventWithOpts = event as BeforeAgentStartEvent & {
+      systemPromptOptions?: { contextFiles?: Array<{ path?: string; content?: string }> };
+    };
+
+    captureNativePaths(state, eventWithOpts);
+    // Root/ancestor context files are owned by pi's system prompt.
+    // SuPi never re-injects them; subdirectory injection handles directories below cwd.
+  });
+
+  // ── Subdirectory injection (tool_result) ───────────────────
+
+  pi.on("tool_result", async (event, _ctx) => {
+    const config = loadClaudeMdConfig(_ctx.cwd);
+    if (!config.subdirs) return;
+    if (event.isError) return;
+
+    const filePath = extractPathFromToolEvent(
+      event.toolName,
+      event.input as Record<string, unknown>,
+    );
+    if (!filePath) return;
+
+    const found = filterAlreadyLoaded(
+      findSubdirContextFiles(filePath, _ctx.cwd, config.fileNames),
+      state.nativeContextPaths,
+    );
+    if (found.length === 0) return;
+
+    const dirsToInject = collectStaleDirs(found, {
+      injectedDirs: state.injectedDirs,
+      currentTurn: state.completedTurns,
+      rereadInterval: config.rereadInterval,
+      contextThreshold: config.contextThreshold,
+      contextUsage: _ctx.getContextUsage() as ContextUsage | undefined,
+    });
+    if (dirsToInject.size === 0) return;
+
+    const filesToInject = Array.from(dirsToInject.values()).flat();
+    const contextText = formatSubdirContext(filesToInject, state.completedTurns);
+    if (!contextText) return;
+
+    updateInjectedDirTracking(state, dirsToInject);
+
+    return {
+      content: [...event.content, { type: "text" as const, text: contextText }],
+    };
+  });
+
+  pi.on("resources_discover", () => ({
+    skillPaths: [join(baseDir, "skills")],
+  }));
+}
+
+function captureNativePaths(
+  state: ClaudeMdState,
+  opts: { systemPromptOptions?: { contextFiles?: Array<{ path?: string; content?: string }> } },
+): void {
+  if (!state.firstAgentStart) return;
+  state.firstAgentStart = false;
+  const contextFiles = opts.systemPromptOptions?.contextFiles ?? [];
+  for (const file of contextFiles) {
+    if (file.path) {
+      state.nativeContextPaths.add(file.path);
+    }
+  }
+}
+
+function collectStaleDirs(
+  found: ReturnType<typeof findSubdirContextFiles>,
+  injectionOpts: InjectionCheckOptions,
+): Map<string, typeof found> {
+  const dirsToInject = new Map<string, typeof found>();
+  for (const file of found) {
+    if (shouldInjectSubdir(file.dir, injectionOpts)) {
+      const existing = dirsToInject.get(file.dir) ?? [];
+      existing.push(file);
+      dirsToInject.set(file.dir, existing);
+    }
+  }
+  return dirsToInject;
+}
+
+function updateInjectedDirTracking(
+  state: ClaudeMdState,
+  dirsToInject: Map<string, Array<{ dir: string; relativePath: string }>>,
+): void {
+  for (const [dir, files] of dirsToInject) {
+    const firstFile = files[0];
+    if (firstFile) {
+      state.injectedDirs.set(dir, { turn: state.completedTurns, file: firstFile.relativePath });
+    }
+  }
+}

package/src/config.ts

@@ -0,0 +1,33 @@
+// Configuration for supi-claude-md.
+//
+// Config shape (in supi shared config, "claude-md" section):
+// {
+//   "rereadInterval": 3,      // turns between subdirectory re-reads (0 = off)
+//   "contextThreshold": 80,    // skip injection when context % >= threshold
+//   "subdirs": true,           // enable subdirectory context discovery
+//   "fileNames": ["CLAUDE.md", "AGENTS.md"]  // context file names to look for
+// }
+
+import { loadSupiConfig } from "@mrclrchtr/supi-core";
+
+export interface ClaudeMdConfig {
+  /** Turns between re-reading previously injected subdirectory context. 0 = disabled. Default: 3 */
+  rereadInterval: number;
+  /** Skip injection when context window usage % >= threshold. 0 = always skip, 100 = never skip. Default: 80 */
+  contextThreshold: number;
+  /** Enable subdirectory context discovery. Default: true */
+  subdirs: boolean;
+  /** Context file names to look for (first match per directory). Default: ["CLAUDE.md", "AGENTS.md"] */
+  fileNames: string[];
+}
+
+export const CLAUDE_MD_DEFAULTS: ClaudeMdConfig = {
+  rereadInterval: 3,
+  contextThreshold: 80,
+  subdirs: true,
+  fileNames: ["CLAUDE.md", "AGENTS.md"],
+};
+
+export function loadClaudeMdConfig(cwd: string, homeDir?: string): ClaudeMdConfig {
+  return loadSupiConfig("claude-md", cwd, CLAUDE_MD_DEFAULTS, { homeDir });
+}

package/src/discovery.ts

@@ -0,0 +1,133 @@
+// Context file discovery — walk up from a file's directory toward cwd,
+// finding CLAUDE.md / AGENTS.md (or configured file names) along the way.
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface DiscoveredContextFile {
+  /** Absolute path of the context file */
+  absolutePath: string;
+  /** Path relative to cwd */
+  relativePath: string;
+  /** The directory containing this file */
+  dir: string;
+}
+
+/**
+ * Walk up from a file's directory toward cwd, collecting context files.
+ * Stops at cwd (does not walk above).
+ * Returns files ordered from nearest ancestor to farthest (closest to cwd).
+ */
+export function findSubdirContextFiles(
+  filePath: string,
+  cwd: string,
+  fileNames: string[],
+): DiscoveredContextFile[] {
+  const absFilePath = path.resolve(cwd, filePath);
+  const absCwd = path.resolve(cwd);
+
+  if (!isPathWithinCwd(absFilePath, absCwd)) {
+    return [];
+  }
+
+  const startDir = resolveStartDir(absFilePath);
+  if (!startDir) return [];
+
+  return walkUpForContextFiles(startDir, absCwd, fileNames);
+}
+
+function isPathWithinCwd(absFilePath: string, absCwd: string): boolean {
+  const relativeToFile = path.relative(absCwd, absFilePath);
+  return !relativeToFile.startsWith("..") && !path.isAbsolute(relativeToFile);
+}
+
+function resolveStartDir(absFilePath: string): string | null {
+  try {
+    return fs.statSync(absFilePath).isDirectory() ? absFilePath : path.dirname(absFilePath);
+  } catch {
+    return null;
+  }
+}
+
+function walkUpForContextFiles(
+  startDir: string,
+  absCwd: string,
+  fileNames: string[],
+): DiscoveredContextFile[] {
+  const results: DiscoveredContextFile[] = [];
+  let currentDir = startDir;
+
+  while (true) {
+    if (!isWithinCwd(currentDir, absCwd)) break;
+
+    const found = findFirstContextFile(currentDir, fileNames, absCwd);
+    if (found) results.push(found);
+
+    if (currentDir === absCwd) break;
+
+    const parent = path.dirname(currentDir);
+    if (parent === currentDir) break;
+    currentDir = parent;
+  }
+
+  return results;
+}
+
+function isWithinCwd(dir: string, absCwd: string): boolean {
+  const relDir = path.relative(absCwd, dir);
+  return !relDir.startsWith("..") && (!path.isAbsolute(relDir) || relDir === "");
+}
+
+function findFirstContextFile(
+  dir: string,
+  fileNames: string[],
+  absCwd: string,
+): DiscoveredContextFile | null {
+  for (const fileName of fileNames) {
+    const candidate = path.join(dir, fileName);
+    if (fs.existsSync(candidate)) {
+      return {
+        absolutePath: candidate,
+        relativePath: path.relative(absCwd, candidate),
+        dir,
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Filter out context files already loaded by pi natively.
+ */
+export function filterAlreadyLoaded(
+  found: DiscoveredContextFile[],
+  nativeContextPaths: Set<string>,
+): DiscoveredContextFile[] {
+  return found.filter((f) => !nativeContextPaths.has(f.absolutePath));
+}
+
+/**
+ * Extract file path from a tool event input.
+ * Returns null for unsupported tools.
+ */
+export function extractPathFromToolEvent(
+  toolName: string,
+  input: Record<string, unknown>,
+): string | null {
+  switch (toolName) {
+    case "read":
+    case "write":
+    case "edit":
+    case "ls": {
+      const p = input.path;
+      return typeof p === "string" ? p : null;
+    }
+    case "lsp":
+    case "tree_sitter": {
+      const f = input.file;
+      return typeof f === "string" ? f : null;
+    }
+    default:
+      return null;
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from "./claude-md.ts";

package/src/settings-registration.ts

@@ -0,0 +1,119 @@
+// Claude-MD settings registration for the supi settings registry.
+
+import type { SettingItem } from "@earendil-works/pi-tui";
+import {
+  type ConfigSettingsHelpers,
+  createInputSubmenu,
+  registerConfigSettings,
+} from "@mrclrchtr/supi-core";
+import { CLAUDE_MD_DEFAULTS, type ClaudeMdConfig } from "./config.ts";
+
+const THRESHOLD_VALUES = [
+  "0",
+  "5",
+  "10",
+  "15",
+  "20",
+  "25",
+  "30",
+  "35",
+  "40",
+  "45",
+  "50",
+  "55",
+  "60",
+  "65",
+  "70",
+  "75",
+  "80",
+  "85",
+  "90",
+  "95",
+  "100",
+];
+
+// ── Settings registration ────────────────────────────────────
+
+export function registerClaudeMdSettings(): void {
+  registerConfigSettings({
+    id: "claude-md",
+    label: "Claude-MD",
+    section: "claude-md",
+    defaults: CLAUDE_MD_DEFAULTS,
+    buildItems: (_settings) => buildClaudeMdSettingItems(_settings),
+    // biome-ignore lint/complexity/useMaxParams: ConfigSettingsOptions interface callback
+    persistChange: (_scope, _cwd, settingId, value, helpers) => {
+      handleSettingChange(settingId, value, helpers);
+    },
+  });
+}
+
+function handleSettingChange(
+  settingId: string,
+  value: string,
+  helpers: ConfigSettingsHelpers,
+): void {
+  switch (settingId) {
+    case "subdirs": {
+      helpers.set("subdirs", value === "on");
+      break;
+    }
+    case "rereadInterval": {
+      const num = Number.parseInt(value, 10);
+      helpers.set("rereadInterval", Number.isNaN(num) ? 0 : num);
+      break;
+    }
+    case "contextThreshold": {
+      const num = Number.parseInt(value, 10);
+      helpers.set("contextThreshold", Number.isNaN(num) ? 80 : num);
+      break;
+    }
+    case "fileNames": {
+      const names = value
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+      if (names.length > 0) {
+        helpers.set("fileNames", names);
+      } else {
+        helpers.unset("fileNames");
+      }
+      break;
+    }
+  }
+}
+
+function buildClaudeMdSettingItems(settings: ClaudeMdConfig): SettingItem[] {
+  return [
+    {
+      id: "subdirs",
+      label: "Subdirectory Discovery",
+      description: "Inject CLAUDE.md/AGENTS.md from subdirectories when browsing files",
+      currentValue: settings.subdirs ? "on" : "off",
+      values: ["on", "off"],
+    },
+    {
+      id: "rereadInterval",
+      label: "Subdirectory Re-read Interval",
+      description: "Turns between re-reading previously injected subdirectory context (0 = off)",
+      currentValue: String(settings.rereadInterval),
+      submenu: (currentValue, done) =>
+        createInputSubmenu(currentValue, "Interval (0 = off):", done),
+    },
+    {
+      id: "contextThreshold",
+      label: "Context Threshold",
+      description: "Skip injection when context window usage % ≥ threshold (100 = never skip)",
+      currentValue: String(settings.contextThreshold),
+      values: THRESHOLD_VALUES,
+    },
+    {
+      id: "fileNames",
+      label: "Context File Names",
+      description: "File names to look for in each directory (comma-separated)",
+      currentValue: settings.fileNames.join(", "),
+      submenu: (currentValue, done) =>
+        createInputSubmenu(currentValue, "File names (comma-separated):", done),
+    },
+  ];
+}

package/src/state.ts

@@ -0,0 +1,94 @@
+// Internal state types for supi-claude-md.
+//
+// State is reconstructed from session history on session_start
+// and mutated in-place during the session lifecycle.
+
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+
+export interface InjectedDir {
+  /** Turn number when this directory's context was last injected */
+  turn: number;
+  /** Relative path of the context file that was injected */
+  file: string;
+}
+
+export interface ClaudeMdState {
+  /** Count of completed assistant turns (stopReason: "stop") */
+  completedTurns: number;
+  /** Map of directory path → injection info */
+  injectedDirs: Map<string, InjectedDir>;
+  /** Set of paths already loaded by pi natively (dedup) */
+  nativeContextPaths: Set<string>;
+  /** Whether this is the first before_agent_start (for native path capture) */
+  firstAgentStart: boolean;
+}
+
+export function createInitialState(): ClaudeMdState {
+  return {
+    completedTurns: 0,
+    injectedDirs: new Map(),
+    nativeContextPaths: new Set(),
+    firstAgentStart: true,
+  };
+}
+
+const CONTEXT_TAG_REGEX =
+  /<extension-context\s+source="supi-claude-md"\s+file="([^"]+)"\s+turn="(\d+)">/g;
+
+export function reconstructState(branch: SessionEntry[]): {
+  completedTurns: number;
+  injectedDirs: Map<string, InjectedDir>;
+} {
+  let completedTurns = 0;
+  const injectedDirs = new Map<string, InjectedDir>();
+
+  for (const entry of branch) {
+    if (isCompletedAssistantTurn(entry)) completedTurns++;
+
+    const toolResultContent = getToolResultContent(entry);
+    if (toolResultContent) {
+      extractInjectedDirs(toolResultContent, injectedDirs);
+    }
+  }
+
+  return { completedTurns, injectedDirs };
+}
+
+function isCompletedAssistantTurn(entry: SessionEntry): boolean {
+  return (
+    entry.type === "message" &&
+    entry.message.role === "assistant" &&
+    entry.message.stopReason === "stop"
+  );
+}
+
+function getToolResultContent(entry: SessionEntry): unknown {
+  if (entry.type !== "message" || entry.message.role !== "toolResult") {
+    return undefined;
+  }
+  return entry.message.content;
+}
+
+function extractInjectedDirs(content: unknown, injectedDirs: Map<string, InjectedDir>): void {
+  const parts = content as Array<{ type?: string; text?: string }> | undefined;
+  if (!parts) return;
+
+  for (const part of parts) {
+    if (part.type === "text" && part.text) {
+      parseContextTags(part.text, injectedDirs);
+    }
+  }
+}
+
+function parseContextTags(text: string, injectedDirs: Map<string, InjectedDir>): void {
+  const matches = text.matchAll(CONTEXT_TAG_REGEX);
+  for (const match of matches) {
+    const file = match[1];
+    const turn = Number.parseInt(match[2] ?? "0", 10);
+    if (file) {
+      const lastSlash = Math.max(file.lastIndexOf("/"), file.lastIndexOf("\\"));
+      const dir = lastSlash >= 0 ? file.substring(0, lastSlash) : ".";
+      injectedDirs.set(dir, { turn, file });
+    }
+  }
+}

package/src/subdirectory.ts

@@ -0,0 +1,84 @@
+// Subdirectory context injection logic.
+//
+// Handles formatting discovered context files into <extension-context> blocks
+// and determining whether injection should occur based on staleness.
+
+import * as fs from "node:fs";
+import { wrapExtensionContext } from "@mrclrchtr/supi-core";
+import type { DiscoveredContextFile } from "./discovery.ts";
+import type { InjectedDir } from "./state.ts";
+
+/**
+ * Context usage info from pi's ctx.getContextUsage().
+ */
+export interface ContextUsage {
+  tokens: number | null;
+  contextWindow: number;
+  percent: number | null;
+}
+
+/**
+ * Format discovered context files into <extension-context> blocks.
+ * Each file is read and wrapped individually.
+ */
+export function formatSubdirContext(files: DiscoveredContextFile[], turn: number): string {
+  const parts: string[] = [];
+
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(file.absolutePath, "utf-8").trim();
+      if (content) {
+        parts.push(
+          wrapExtensionContext("supi-claude-md", content, {
+            file: file.relativePath,
+            turn,
+          }),
+        );
+      }
+    } catch {
+      // File may have been deleted between discovery and read
+    }
+  }
+
+  return parts.join("\n\n");
+}
+
+export interface InjectionCheckOptions {
+  injectedDirs: Map<string, InjectedDir>;
+  currentTurn: number;
+  rereadInterval: number;
+  contextThreshold: number;
+  contextUsage?: ContextUsage;
+}
+
+/**
+ * Determine if subdirectory context should be injected.
+ * Returns true if:
+ * - The directory has not been injected yet (always, even under context pressure)
+ * - The directory was injected but is stale (turn delta >= rereadInterval)
+ *   AND context usage is below the threshold
+ * - rereadInterval is 0 (disabled — always false for re-injections)
+ */
+export function shouldInjectSubdir(dir: string, options: InjectionCheckOptions): boolean {
+  const { injectedDirs, currentTurn, rereadInterval, contextThreshold, contextUsage } = options;
+
+  // Never-injected directory: always inject (even when rereadInterval is 0)
+  // First-time discovery is always allowed regardless of context pressure
+  const injected = injectedDirs.get(dir);
+  if (!injected) return true;
+
+  // Already-injected directory: skip if reread is disabled
+  if (rereadInterval === 0) return false;
+
+  // Re-injection: skip when context usage is at or above threshold
+  if (
+    contextThreshold < 100 &&
+    contextUsage &&
+    contextUsage.percent != null &&
+    contextUsage.percent >= contextThreshold
+  ) {
+    return false;
+  }
+
+  return currentTurn - injected.turn >= rereadInterval;
+}