feat: add --hook flag for AI agent integration

Add --hook flag that reads JSON from stdin, extracts file path from
common field patterns, and fixes markdown files in-place. Designed
for seamless integration with AI coding agent hook systems.

Supported JSON formats:
- tool_input.file_path (Claude Code)
- file_path (Cursor, Windsurf)
- filePath (camelCase variant)
- path (minimal)

Key behaviors:
- Silently skips non-.md files
- Always exits 0 to never break agentic workflows
- Works with Claude Code, Cursor, Windsurf, OpenCode

Includes:
- extractFilePath() function with 11 unit tests
- Updated README with docs for all supported agents
- Local .claude/settings.json hook config for testing

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: kmelve

.claude/settings.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/dist/cli.js\" --hook"
+          }
+        ]
+      }
+    ]
+  }
+}

README.md

@@ -5,8 +5,8 @@ Fix misaligned ASCII diagram borders in markdown files.
 ```
 Before                          After
 ┌─────────────────────┐         ┌─────────────────────┐
-│ Component A        │    →    │ Component A         │
-│ with content       │         │ with content        │
+│ Component A        │    →     │ Component A         │
+│ with content       │          │ with content        │
 └─────────────────────┘         └─────────────────────┘
 ```
 
@@ -71,6 +71,7 @@ boxfix doc1.md doc2.md --in-place
 | `--json` | `-j` | Output results as JSON |
 | `--dry-run` | `-d` | Preview changes without modifying |
 | `--quiet` | `-q` | Suppress output except errors |
+| `--hook` | | Read JSON from stdin, extract file path, fix in-place (for AI agents) |
 
 ### JSON Output
 
@@ -233,11 +234,31 @@ jobs:
       - run: npx @sanity-labs/boxfix --check **/*.md
 ```
 
-### Claude Code
+### AI Agent Hooks
 
-Automatically fix diagrams as Claude writes them using [hooks](https://docs.anthropic.com/en/docs/claude-code/hooks).
+The `--hook` flag enables seamless integration with AI coding agents. It reads JSON from stdin, extracts the file path from common field patterns, and silently processes markdown files.
 
-Add this to your project's `.claude/settings.json`:
+**Key features:**
+- Reads JSON payload from stdin (as provided by agent hooks)
+- Extracts file path from common JSON structures
+- Silently skips non-markdown files
+- Always exits 0 to never break agentic workflows
+- Works with Claude Code, Cursor, Windsurf, and other agents
+
+**Supported JSON formats:**
+
+| Format | Example | Used by |
+|--------|---------|---------|
+| `tool_input.file_path` | `{"tool_input":{"file_path":"..."}}` | Claude Code |
+| `file_path` | `{"file_path":"..."}` | Cursor, Windsurf |
+| `filePath` | `{"filePath":"..."}` | Generic (camelCase) |
+| `path` | `{"path":"..."}` | Minimal |
+
+#### Claude Code
+
+Automatically fix diagrams as Claude writes them using [hooks](https://code.claude.com/docs/en/hooks).
+
+Add to `.claude/settings.json`:
 
 ```json
 {
@@ -248,7 +269,7 @@ Add this to your project's `.claude/settings.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "npx @sanity-labs/boxfix \"$(jq -r '.tool_input.file_path // empty')\" --in-place 2>/dev/null || true"
+            "command": "npx @sanity-labs/boxfix --hook"
           }
         ]
       }
@@ -257,7 +278,45 @@ Add this to your project's `.claude/settings.json`:
 }
 ```
 
-This runs boxfix on any markdown file Claude creates or edits, silently fixing diagram borders in the background.
+#### Cursor
+
+Cursor 1.7+ supports [hooks](https://cursor.com/docs/agent/hooks) for agent lifecycle control.
+
+Add to `.cursor/hooks.json`:
+
+```json
+{
+  "afterFileEdit": [
+    {
+      "command": "npx @sanity-labs/boxfix --hook"
+    }
+  ]
+}
+```
+
+#### Windsurf
+
+Windsurf (Codeium) supports [Cascade Hooks](https://docs.windsurf.com/windsurf/cascade/hooks) for automation.
+
+Add to `.windsurf/hooks.json`:
+
+```json
+{
+  "post_write_code": [
+    {
+      "command": "npx @sanity-labs/boxfix --hook"
+    }
+  ]
+}
+```
+
+#### OpenCode
+
+OpenCode supports plugins for extensibility. You can use the [oh-my-opencode](https://www.npmjs.com/package/oh-my-opencode) package which provides Claude Code hook compatibility, or create a custom plugin.
+
+#### Other Agents
+
+For any agent that pipes JSON with a file path to stdin on file edit events, the `--hook` flag should work out of the box. The tool checks for file paths in common locations (see table above) and silently exits 0 if no valid markdown path is found.
 
 ## Why "boxfix"?
 

src/cli.ts

@@ -1,9 +1,78 @@
 #!/usr/bin/env node
 import { program } from "commander";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { glob } from "glob";
 import { boxfixMarkdown } from "./markdown.js";
 
+/**
+ * Extract file path from common JSON field patterns used by AI agents.
+ * Supports multiple formats for agent-agnostic integration.
+ */
+export function extractFilePath(json: unknown): string | null {
+  if (!json || typeof json !== "object") return null;
+  const obj = json as Record<string, unknown>;
+
+  // Check common path locations (order of precedence)
+  const candidates = [
+    (obj.tool_input as Record<string, unknown>)?.file_path, // Claude Code, Cursor
+    obj.file_path, // Generic
+    obj.filePath, // camelCase variant
+    (obj.input as Record<string, unknown>)?.file_path, // Nested input object
+    obj.path, // Minimal
+  ];
+
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.length > 0) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Read JSON from stdin and extract file path for hook processing.
+ * Returns null if stdin is TTY, JSON is invalid, or path is not a markdown file.
+ */
+async function readHookInput(): Promise<string | null> {
+  // Return null if stdin is TTY (no piped input)
+  if (process.stdin.isTTY) {
+    return null;
+  }
+
+  // Read all stdin
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const input = Buffer.concat(chunks).toString("utf-8").trim();
+
+  if (!input) {
+    return null;
+  }
+
+  // Parse JSON
+  let json: unknown;
+  try {
+    json = JSON.parse(input);
+  } catch {
+    return null;
+  }
+
+  // Extract file path
+  const filePath = extractFilePath(json);
+  if (!filePath) {
+    return null;
+  }
+
+  // Only process markdown files
+  if (!filePath.endsWith(".md") && !filePath.endsWith(".markdown")) {
+    return null;
+  }
+
+  return filePath;
+}
+
 interface FileResult {
   file: string;
   linesFixed: number;
@@ -25,15 +94,44 @@ program
   .name("boxfix")
   .description("Fix misaligned ASCII diagram borders in markdown files")
   .version("1.0.0")
-  .argument("<patterns...>", "File path(s) or glob pattern(s) to process")
+  .argument("[patterns...]", "File path(s) or glob pattern(s) to process")
   .option("-o, --output <file>", "Output to file (only valid with single input)")
   .option("-i, --in-place", "Modify files in place")
   .option("-d, --dry-run", "Show what would be changed without modifying files")
   .option("-q, --quiet", "Suppress output except errors")
   .option("-c, --check", "Check if files need fixing (exit code 1 if fixes needed)")
   .option("-j, --json", "Output results as JSON")
+  .option(
+    "--hook",
+    "Read JSON from stdin, extract file path, and fix in-place (for agent integration)"
+  )
   .action(async (patterns: string[], options) => {
-    const { output, inPlace, dryRun, quiet, check, json } = options;
+    const { output, inPlace, dryRun, quiet, check, json, hook } = options;
+
+    // Hook mode: read JSON from stdin and process file
+    if (hook) {
+      const filePath = await readHookInput();
+      if (!filePath || !existsSync(filePath)) {
+        process.exit(0); // Silent success
+      }
+
+      try {
+        const content = readFileSync(filePath, "utf-8");
+        const result = boxfixMarkdown(content);
+        if (result.stats.linesFixed > 0) {
+          writeFileSync(filePath, result.fixed, "utf-8");
+        }
+      } catch {
+        // Ignore errors in hook mode
+      }
+      process.exit(0);
+    }
+
+    // Normal mode requires patterns
+    if (!patterns || patterns.length === 0) {
+      console.error("Error: No files specified");
+      process.exit(1);
+    }
 
     // Expand glob patterns
     const files: string[] = [];
@@ -183,4 +281,12 @@ program
     }
   });
 
-program.parse();
+// Only run when executed directly, not when imported
+const isMain =
+  typeof import.meta.url !== "undefined" &&
+  process.argv[1] &&
+  fileURLToPath(import.meta.url) === process.argv[1];
+
+if (isMain) {
+  program.parse();
+}

test/boxfix.test.ts

@@ -3,6 +3,7 @@ import { boxfix, boxfixDiagram } from "../src/boxfix.js";
 import { boxfixMarkdown } from "../src/markdown.js";
 import { getDisplayWidth, expandTabs } from "../src/width.js";
 import { isDiagram, isBoundaryLine, isContentLine, isTreeLine } from "../src/diagram-detector.js";
+import { extractFilePath } from "../src/cli.js";
 
 describe("getDisplayWidth", () => {
   it("calculates width of ASCII string", () => {
@@ -254,3 +255,63 @@ Text between.
     expect(result.stats.blocksProcessed).toBe(2);
   });
 });
+
+describe("extractFilePath", () => {
+  it("extracts path from Claude Code format (tool_input.file_path)", () => {
+    const json = { tool_input: { file_path: "docs/readme.md" } };
+    expect(extractFilePath(json)).toBe("docs/readme.md");
+  });
+
+  it("extracts path from generic format (file_path)", () => {
+    const json = { file_path: "test.md" };
+    expect(extractFilePath(json)).toBe("test.md");
+  });
+
+  it("extracts path from camelCase format (filePath)", () => {
+    const json = { filePath: "example.md" };
+    expect(extractFilePath(json)).toBe("example.md");
+  });
+
+  it("extracts path from nested input format (input.file_path)", () => {
+    const json = { input: { file_path: "nested/file.md" } };
+    expect(extractFilePath(json)).toBe("nested/file.md");
+  });
+
+  it("extracts path from minimal format (path)", () => {
+    const json = { path: "simple.md" };
+    expect(extractFilePath(json)).toBe("simple.md");
+  });
+
+  it("prefers tool_input.file_path over other fields", () => {
+    const json = {
+      tool_input: { file_path: "priority.md" },
+      file_path: "fallback.md",
+      path: "last.md",
+    };
+    expect(extractFilePath(json)).toBe("priority.md");
+  });
+
+  it("returns null for empty object", () => {
+    expect(extractFilePath({})).toBe(null);
+  });
+
+  it("returns null for null input", () => {
+    expect(extractFilePath(null)).toBe(null);
+  });
+
+  it("returns null for non-object input", () => {
+    expect(extractFilePath("string")).toBe(null);
+    expect(extractFilePath(123)).toBe(null);
+    expect(extractFilePath(undefined)).toBe(null);
+  });
+
+  it("returns null for empty string path", () => {
+    const json = { file_path: "" };
+    expect(extractFilePath(json)).toBe(null);
+  });
+
+  it("returns null when no recognizable path field exists", () => {
+    const json = { something_else: "value.md" };
+    expect(extractFilePath(json)).toBe(null);
+  });
+});