@levnikolaevich/hex-line-mcp 1.0.0 → 1.1.0

package/lib/bulk-replace.mjs

@@ -23,6 +23,8 @@ export function bulkReplace(rootDir, globPattern, replacements, opts = {}) {
 
     const results = [];
     let changed = 0, skipped = 0, errors = 0;
+    const MAX_OUTPUT = 80000;
+    let totalChars = 0;
 
     for (const file of files) {
         try {
@@ -44,6 +46,12 @@ export function bulkReplace(rootDir, globPattern, replacements, opts = {}) {
             const relPath = file.replace(abs, "").replace(/^[/\\]/, "");
             results.push(`--- ${relPath}\n${diff || "(no visible diff)"}`);
             changed++;
+            totalChars += results[results.length - 1].length;
+            if (totalChars > MAX_OUTPUT) {
+                const remaining = files.length - files.indexOf(file) - 1;
+                if (remaining > 0) results.push(`OUTPUT_CAPPED: ${remaining} more files not shown. Output exceeded ${MAX_OUTPUT} chars.`);
+                break;
+            }
         } catch (e) {
             results.push(`ERROR: ${file}: ${e.message}`);
             errors++;

package/lib/coerce.mjs

@@ -24,10 +24,15 @@ const ALIASES = {
     // edit_file
     dryRun: "dry_run",
     "dry-run": "dry_run",
+    restoreIndent: "restore_indent",
+    "restore-indent": "restore_indent",
 
     // directory_tree
     maxDepth: "max_depth",
     depth: "max_depth",
+    name: "pattern",
+    filter: "pattern",
+    entry_type: "type",
 };
 
 export function coerceParams(params) {

package/lib/edit.mjs

@@ -65,7 +65,23 @@ function buildHashIndex(lines) {
 function findLine(lines, lineNum, expectedTag, hashIndex) {
     const idx = lineNum - 1;
     if (idx < 0 || idx >= lines.length) {
-        throw new Error(`Line ${lineNum} out of range (1-${lines.length})`);
+        const start = idx >= lines.length
+            ? Math.max(0, lines.length - 10)
+            : 0;
+        const end = idx >= lines.length
+            ? lines.length
+            : Math.min(lines.length, 10);
+        const snippet = lines.slice(start, end).map((line, i) => {
+            const num = start + i + 1;
+            const tag = lineTag(fnv1a(line));
+            return `${tag}.${num}\t${line}`;
+        }).join("\n");
+
+        throw new Error(
+            `Line ${lineNum} out of range (1-${lines.length}).\n\n` +
+            `Current content (lines ${start + 1}-${end}):\n${snippet}\n\n` +
+            `Tip: Use updated hashes above for retry.`
+        );
     }
 
     const actual = lineTag(fnv1a(lines[idx]));
@@ -212,7 +228,8 @@ function buildSnippet(norm, charPos) {
     const end = Math.min(lines.length, start + 10);
     const snippetLines = [];
     for (let i = start; i < end; i++) {
-        snippetLines.push(`  ${i + 1}| ${lines[i]}`);
+        const tag = lineTag(fnv1a(lines[i]));
+        snippetLines.push(`${tag}.${i + 1}\t${lines[i]}`);
     }
     return { start: start + 1, end, text: snippetLines.join("\n") };
 }
@@ -242,7 +259,7 @@ function textReplace(content, oldText, newText, all) {
             throw new Error(
                 `TEXT_NOT_FOUND: "${normOld.slice(0, 100)}..." not found.\n\n` +
                 `Nearest content (lines ${snip.start}-${snip.end}):\n${snip.text}\n\n` +
-                `Tip: Re-read file or adjust old_text to match actual content.`
+                `Tip: Use hashes above for anchor-based edit, or adjust old_text.`
             );
         }
     }
@@ -269,37 +286,54 @@ function textReplace(content, oldText, newText, all) {
         return norm.split(normOld).join(normNew);
     }
 
-    // Check for multiple matches
+    // Check for multiple matches — return hash-hint instead of opaque error
+    const positions = [];
     if (confusableMatch) {
         const normContent = normalizeConfusables(norm);
         const normSearch = normalizeConfusables(normOld);
-        if (normContent.indexOf(normSearch, idx + 1) !== -1) {
-            throw new Error("MULTIPLE_MATCHES: Found multiple occurrences. Use all:true or add more context for unique match.");
+        let searchPos = 0;
+        while ((searchPos = normContent.indexOf(normSearch, searchPos)) !== -1) {
+            positions.push(searchPos);
+            searchPos += normSearch.length;
+        }
+    } else {
+        let searchPos = 0;
+        while ((searchPos = norm.indexOf(normOld, searchPos)) !== -1) {
+            positions.push(searchPos);
+            searchPos += normOld.length;
         }
-    } else if (norm.indexOf(normOld, idx + 1) !== -1) {
-        throw new Error("MULTIPLE_MATCHES: Found multiple occurrences. Use all:true or add more context for unique match.");
+    }
+
+    if (positions.length > 1) {
+        const allLines = norm.split("\n");
+        const matchLineCount = normOld.split("\n").length;
+        const snippets = positions.map((charPos, i) => {
+            let cumLen = 0, matchLine = 0;
+            for (let l = 0; l < allLines.length; l++) {
+                cumLen += allLines[l].length + 1;
+                if (cumLen > charPos) { matchLine = l; break; }
+            }
+            const start = Math.max(0, matchLine - 1);
+            const end = Math.min(allLines.length, matchLine + matchLineCount + 1);
+            const lines = allLines.slice(start, end).map((line, j) => {
+                const num = start + j + 1;
+                const tag = lineTag(fnv1a(line));
+                return `${tag}.${num}\t${line}`;
+            });
+            return `Match ${i + 1} (lines ${start + 1}-${end}):\n${lines.join("\n")}`;
+        });
+
+        throw new Error(
+            `HASH_HINT: Found ${positions.length} match(es) for replace. Use anchor-based edit for precision.\n\n` +
+            snippets.join("\n\n") +
+            `\n\nRetry with: [{"set_line":{"anchor":"XX.NN","new_text":"..."}}] or [{"replace_lines":{"start_anchor":"XX.NN","end_anchor":"YY.MM","new_text":"..."}}]`
+        );
     }
 
     return norm.slice(0, idx) + normNew + norm.slice(idx + matchLen);
 }
 
-/**
- * Strip boundary echo lines from replacement text.
- * Agents often echo the start/end anchor lines in their replacement — strip them
- * to avoid duplicating boundary content.
- */
-function stripBoundaryEcho(lines, startIdx, endIdx, newLines) {
-    let result = [...newLines];
-    // Strip start boundary echo
-    if (result.length > 0 && lines[startIdx].trim() === result[0].trim()) {
-        result = result.slice(1);
-    }
-    // Strip end boundary echo
-    if (result.length > 0 && lines[endIdx].trim() === result[result.length - 1].trim()) {
-        result = result.slice(0, -1);
-    }
-    return result;
-}
+
 
 /**
  * Apply edits to a file.
@@ -347,7 +381,8 @@ export function editFile(filePath, edits, opts = {}) {
                 lines.splice(idx, 1);
             } else {
                 const origLine = [lines[idx]];
-                const newLines = restoreIndent(origLine, String(txt).split("\n"));
+                const raw = String(txt).split("\n");
+                const newLines = opts.restoreIndent ? restoreIndent(origLine, raw) : raw;
                 lines.splice(idx, 1, ...newLines);
             }
         } else if (e.replace_lines) {
@@ -360,14 +395,16 @@ export function editFile(filePath, edits, opts = {}) {
                 lines.splice(si, ei - si + 1);
             } else {
                 const origLines = lines.slice(si, ei + 1);
-                let newLines = stripBoundaryEcho(lines, si, ei, String(txt).split("\n"));
-                newLines = restoreIndent(origLines, newLines);
+                let newLines = String(txt).split("\n");
+                if (opts.restoreIndent) newLines = restoreIndent(origLines, newLines);
                 lines.splice(si, ei - si + 1, ...newLines);
             }
         } else if (e.insert_after) {
             const { tag, line } = parseRef(e.insert_after.anchor);
             const idx = findLine(lines, line, tag, hashIndex);
-            lines.splice(idx + 1, 0, ...e.insert_after.text.split("\n"));
+            let insertLines = e.insert_after.text.split("\n");
+            if (opts.restoreIndent) insertLines = restoreIndent([lines[idx]], insertLines);
+            lines.splice(idx + 1, 0, ...insertLines);
         }
     }
 
@@ -379,10 +416,13 @@ export function editFile(filePath, edits, opts = {}) {
     }
 
     if (original === content) {
-        throw new Error("NOOP_EDIT: All edits produced identical content. File unchanged. Re-read to verify current state.");
+        throw new Error("NOOP_EDIT: File already contains the desired content. No changes needed.");
     }
 
-    const diff = simpleDiff(origLines, content.split("\n"));
+    let diff = simpleDiff(origLines, content.split("\n"));
+    if (diff && diff.length > 80000) {
+        diff = diff.slice(0, 80000) + `\n... (diff truncated, ${diff.length} chars total)`;
+    }
 
     if (opts.dryRun) {
         let msg = `Dry run: ${filePath} would change (${content.split("\n").length} lines)`;

package/lib/read.mjs

@@ -29,6 +29,7 @@ function relativeTime(date) {
 }
 
 const DEFAULT_LIMIT = 2000;
+const MAX_OUTPUT_CHARS = 80000;
 
 /**
  * Read a file with hash-annotated lines.
@@ -67,32 +68,44 @@ export function readFile(filePath, opts = {}) {
 
     const parts = [];
 
+    let cappedAtLine = 0;
+
     for (const range of ranges) {
         const selected = lines.slice(range.start - 1, range.end);
         const lineHashes = [];
+        const formatted = [];
+        let charCount = 0;
+
+        for (let i = 0; i < selected.length; i++) {
+            const line = selected[i];
+            const num = range.start + i;
+            const hash32 = fnv1a(line);
+            const entry = opts.plain
+                ? `${num}|${line}`
+                : `${lineTag(hash32)}.${num}\t${line}`;
 
-        let formatted;
-        if (opts.plain) {
-            formatted = selected.map((line, i) => {
-                const num = range.start + i;
-                lineHashes.push(fnv1a(line));
-                return `${num}|${line}`;
-            }).join("\n");
-        } else {
-            formatted = selected.map((line, i) => {
-                const num = range.start + i;
-                const hash32 = fnv1a(line);
-                lineHashes.push(hash32);
-                const tag = lineTag(hash32);
-                return `${tag}.${num}\t${line}`;
-            }).join("\n");
+            if (charCount + entry.length > MAX_OUTPUT_CHARS && formatted.length > 0) {
+                cappedAtLine = num;
+                break;
+            }
+            lineHashes.push(hash32);
+            formatted.push(entry);
+            charCount += entry.length + 1;
         }
 
-        parts.push(formatted);
+        // Update range end to actual lines shown
+        const actualEnd = formatted.length > 0
+            ? range.start + formatted.length - 1
+            : range.start;
+        range.end = actualEnd;
+
+        parts.push(formatted.join("\n"));
 
-        // Range checksum
-        const cs = rangeChecksum(lineHashes, range.start, range.end);
+        // Range checksum (only for lines actually shown)
+        const cs = rangeChecksum(lineHashes, range.start, actualEnd);
         parts.push(`\nchecksum: ${cs}`);
+
+        if (cappedAtLine) break;
     }
 
     // Header
@@ -125,5 +138,17 @@ export function readFile(filePath, opts = {}) {
         }
     }
 
-    return `${header}${graphLine}\n\n\`\`\`\n${parts.join("\n")}\n\`\`\``;
+    let result = `${header}${graphLine}\n\n\`\`\`\n${parts.join("\n")}\n\`\`\``;
+
+    // Auto-hint for large files read from start without offset
+    if (total > 200 && (!opts.offset || opts.offset <= 1) && !cappedAtLine) {
+        result += `\n\n\u26A1 Tip: This file has ${total} lines. Use outline first, then read_file with offset/limit for 75% fewer tokens.`;
+    }
+
+    // Character cap notice
+    if (cappedAtLine) {
+        result += `\n\nOUTPUT_CAPPED at line ${cappedAtLine} (${MAX_OUTPUT_CHARS} char limit). Use offset=${cappedAtLine} to continue reading.`;
+    }
+
+    return result;
 }

package/lib/setup.mjs

@@ -2,13 +2,33 @@
  * Setup hex-line hooks for CLI agents.
  *
  * Idempotent: re-running with same config produces no changes.
- * Supports: claude (hooks in settings.local.json), gemini, codex (info only).
+ * Supports: claude (hooks in ~/.claude/settings.json global), gemini, codex (info only).
+ * Cleanup: removes old per-project hooks from .claude/settings.local.json.
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
 
-const HOOK_COMMAND = "node mcp/hex-line-mcp/hook.mjs";
+// Resolve absolute path to hook.mjs at module load time.
+// setup.mjs is in lib/, hook.mjs is one level up (sibling of lib/).
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const HOOK_SCRIPT = resolve(__dirname, "..", "hook.mjs").replace(/\\/g, "/");
+const HOOK_COMMAND = `node ${HOOK_SCRIPT}`;
+
+// Legacy relative command — needed to find and remove old per-project hooks.
+const OLD_HOOK_COMMAND = "node mcp/hex-line-mcp/hook.mjs";
+
+// Substring that identifies any hex-line hook command (old relative or new absolute).
+const HOOK_SIGNATURE = "hex-line-mcp/hook.mjs";
+
+const NPX_MARKERS = ["_npx", "npx-cache", ".npm/_npx"];
+
+function isEphemeralInstall(scriptPath) {
+    return NPX_MARKERS.some((m) => scriptPath.includes(m));
+}
 
 const CLAUDE_HOOKS = {
     SessionStart: {
@@ -38,21 +58,21 @@ function writeJson(filePath, data) {
 }
 
 /**
- * Find existing hook entry index by command substring.
- * @param {Array} entries - Array of {matcher, hooks[]} objects
- * @param {string} command - Command string to match
- * @returns {number} Index or -1
+ * Find existing hook entry index by hex-line signature substring.
+ * Catches both old relative ("node mcp/hex-line-mcp/hook.mjs") and
+ * new absolute ("node d:/.../hex-line-mcp/hook.mjs") commands.
  */
-function findEntryByCommand(entries, command) {
+function findEntryByCommand(entries) {
     return entries.findIndex(
-        (e) => Array.isArray(e.hooks) && e.hooks.some((h) => h.command === command)
+        (e) => Array.isArray(e.hooks) && e.hooks.some((h) =>
+            typeof h.command === "string" && h.command.includes(HOOK_SIGNATURE)
+        )
     );
 }
 
-// ---- Agent configurators ----
+// ---- Core: write hooks to a settings file ----
 
-function setupClaude() {
-    const settingsPath = resolve(process.cwd(), ".claude/settings.local.json");
+function writeHooksToFile(settingsPath, label) {
     const config = readJson(settingsPath) || {};
 
     if (!config.hooks || typeof config.hooks !== "object") {
@@ -67,17 +87,17 @@ function setupClaude() {
         }
 
         const entries = config.hooks[event];
-        const idx = findEntryByCommand(entries, HOOK_COMMAND);
+        const idx = findEntryByCommand(entries);
 
         if (idx >= 0) {
-            // Entry exists — check if matcher and timeout match
             const existing = entries[idx];
             if (existing.matcher === desired.matcher &&
                 existing.hooks.length === desired.hooks.length &&
+                existing.hooks[0].command === HOOK_COMMAND &&
                 existing.hooks[0].timeout === desired.hooks[0].timeout) {
                 continue; // Already configured exactly
             }
-            // Update in place
+            // Update in place (path changed or config updated)
             entries[idx] = { matcher: desired.matcher, hooks: [...desired.hooks] };
             changed = true;
         } else {
@@ -92,11 +112,108 @@ function setupClaude() {
     }
 
     if (!changed) {
-        return "Claude: already configured, no changes";
+        return `Claude (${label}): already configured`;
     }
 
     writeJson(settingsPath, config);
-    return "Claude: PreToolUse + PostToolUse -> mcp/hex-line-mcp/hook.mjs OK";
+    return `Claude (${label}): hooks -> ${HOOK_SCRIPT} OK`;
+}
+
+// ---- Cleanup: remove hex-line hooks from per-project file ----
+
+function cleanLocalHooks() {
+    const localPath = resolve(process.cwd(), ".claude/settings.local.json");
+    const config = readJson(localPath);
+
+    if (!config || !config.hooks || typeof config.hooks !== "object") {
+        return "local: clean";
+    }
+
+    let changed = false;
+
+    for (const event of Object.keys(CLAUDE_HOOKS)) {
+        if (!Array.isArray(config.hooks[event])) continue;
+
+        const entries = config.hooks[event];
+        const idx = findEntryByCommand(entries);
+
+        if (idx >= 0) {
+            entries.splice(idx, 1);
+            changed = true;
+        }
+
+        // Remove empty arrays
+        if (entries.length === 0) {
+            delete config.hooks[event];
+        }
+    }
+
+    // Remove empty hooks object
+    if (Object.keys(config.hooks).length === 0) {
+        delete config.hooks;
+    }
+
+    if (!changed) {
+        return "local: clean";
+    }
+
+    writeJson(localPath, config);
+    return "local: removed old hex-line hooks";
+}
+
+// ---- Output Style installer ----
+
+function installOutputStyle() {
+    const source = resolve(dirname(fileURLToPath(import.meta.url)), "..", "output-style.md");
+    const target = resolve(homedir(), ".claude", "output-styles", "hex-line.md");
+
+    // Copy output-style.md to ~/.claude/output-styles/
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, readFileSync(source, "utf-8"), "utf-8");
+
+    // Check outputStyle in all scopes (Local > Project > User)
+    const scopes = [
+        { path: resolve(process.cwd(), ".claude/settings.local.json"), label: "local" },
+        { path: resolve(process.cwd(), ".claude/settings.json"), label: "project" },
+        { path: resolve(homedir(), ".claude/settings.json"), label: "user" },
+    ];
+
+    for (const scope of scopes) {
+        const config = readJson(scope.path);
+        if (config && config.outputStyle) {
+            return `Output style 'hex-line' installed to ~/.claude/output-styles/. Current style '${config.outputStyle}' preserved (scope: ${scope.label}). Switch via /config > Output style`;
+        }
+    }
+
+    // No outputStyle set anywhere — activate hex-line at user level
+    const userSettings = resolve(homedir(), ".claude/settings.json");
+    const config = readJson(userSettings) || {};
+    config.outputStyle = "hex-line";
+    writeJson(userSettings, config);
+    return "Output style 'hex-line' installed and activated in ~/.claude/settings.json";
+}
+
+// ---- Agent configurators ----
+
+function setupClaude() {
+    if (isEphemeralInstall(HOOK_SCRIPT)) {
+        return "Claude: SKIPPED — hook.mjs is in npx cache (ephemeral). " +
+            "Install permanently: npm i -g @levnikolaevich/hex-line-mcp, then re-run setup_hooks.";
+    }
+
+    const results = [];
+
+    // Phase A: write hooks to global ~/.claude/settings.json
+    const globalPath = resolve(homedir(), ".claude/settings.json");
+    results.push(writeHooksToFile(globalPath, "global"));
+
+    // Phase B: remove hex-line hooks from per-project settings.local.json
+    results.push(cleanLocalHooks());
+
+    // Phase C: install Output Style
+    results.push(installOutputStyle());
+
+    return results.join(" | ");
 }
 
 function setupGemini() {
@@ -113,6 +230,7 @@ const AGENTS = { claude: setupClaude, gemini: setupGemini, codex: setupCodex };
 
 /**
  * Configure hex-line hooks for one or all supported agents.
+ * Claude: writes to ~/.claude/settings.json (global), cleans per-project hooks.
  * @param {string} [agent="all"] - "claude", "gemini", "codex", or "all"
  * @returns {string} Status report
  */

package/lib/tree.mjs

@@ -6,12 +6,26 @@
  */
 
 import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
-import { resolve, basename, join } from "node:path";
+import { resolve, basename, join, relative } from "node:path";
 
 const SKIP_DIRS = new Set([
     "node_modules", ".git", "dist", "build", "__pycache__", ".next", "coverage",
 ]);
 
+/**
+ * Convert a simple glob pattern to a RegExp.
+ * Supports: * (any non-slash), ** (any), ? (single char).
+ */
+function globToRegex(pat) {
+    return new RegExp(
+        "^" + pat.replace(/[.+^${}()|[\]\\]/g, "\\$&")
+                  .replace(/\*\*/g, "\0")
+                  .replace(/\*/g, "[^/]*")
+                  .replace(/\0/g, ".*")
+                  .replace(/\?/g, ".") + "$"
+    );
+}
+
 /**
  * Parse .gitignore into match functions.
  * Supports: comments (#), negation (!), wildcards (*), dir-only trailing /.
@@ -29,15 +43,11 @@ function parseGitignore(content) {
         // Strip trailing /
         const dirOnly = pat.endsWith("/");
         if (dirOnly) pat = pat.slice(0, -1);
-        // Convert glob to regex
-        const re = new RegExp(
-            "^" + pat.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "\0").replace(/\*/g, "[^/]*").replace(/\0/g, ".*").replace(/\?/g, ".") + "$"
-        );
+        const re = globToRegex(pat);
         patterns.push({ re, negate, dirOnly });
     }
     return patterns;
 }
-
 function isIgnored(name, isDir, patterns) {
     let ignored = false;
     for (const { re, negate, dirOnly } of patterns) {
@@ -54,12 +64,77 @@ function formatSize(bytes) {
 }
 
 /**
- * Build directory tree recursively.
+ * Find files/dirs by glob pattern. Returns flat list of relative paths.
+ * @param {string} dirPath - Root directory to search
+ * @param {object} opts - { pattern, type, max_depth, gitignore }
+ * @returns {string} Formatted match list
+ */
+function findByPattern(dirPath, opts) {
+    const re = globToRegex(opts.pattern);
+    const filterType = opts.type || "all";
+    const maxDepth = opts.max_depth ?? 20;
+    const useGitignore = opts.gitignore ?? true;
+
+    const normalized = (process.platform === "win32" && /^\/[a-zA-Z]\//.test(dirPath))
+        ? dirPath[1] + ":" + dirPath.slice(2) : dirPath;
+    const abs = resolve(normalized);
+    if (!existsSync(abs)) throw new Error(`DIRECTORY_NOT_FOUND: ${abs}`);
+    if (!statSync(abs).isDirectory()) throw new Error(`Not a directory: ${abs}`);
+
+    let patterns = [];
+    if (useGitignore) {
+        const gi = join(abs, ".gitignore");
+        if (existsSync(gi)) {
+            try { patterns = parseGitignore(readFileSync(gi, "utf-8")); } catch { /* skip */ }
+        }
+    }
+
+    const matches = [];
+
+    function walk(dir, depth) {
+        if (depth > maxDepth) return;
+        let entries;
+        try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+
+        for (const entry of entries) {
+            const isDir = entry.isDirectory();
+            if (SKIP_DIRS.has(entry.name) && isDir) continue;
+            if (isIgnored(entry.name, isDir, patterns)) continue;
+
+            const full = join(dir, entry.name);
+
+            if (re.test(entry.name)) {
+                if (filterType === "all" ||
+                    (filterType === "dir" && isDir) ||
+                    (filterType === "file" && !isDir)) {
+                    const rel = relative(abs, full).replace(/\\/g, "/");
+                    matches.push(isDir ? rel + "/" : rel);
+                }
+            }
+
+            if (isDir) walk(full, depth + 1);
+        }
+    }
+
+    walk(abs, 1);
+    matches.sort();
+
+    const rootName = basename(abs);
+    if (matches.length === 0) {
+        return `No matches for "${opts.pattern}" in ${rootName}/`;
+    }
+    return `Found ${matches.length} match${matches.length === 1 ? "" : "es"} for "${opts.pattern}" in ${rootName}/\n\n${matches.join("\n")}`;
+}
+
+/**
+ * Build directory tree recursively, or find by pattern.
  * @param {string} dirPath - Absolute directory path
- * @param {object} opts - { max_depth, gitignore, format }
- * @returns {string} Formatted tree
+ * @param {object} opts - { max_depth, gitignore, format, pattern, type }
+ * @returns {string} Formatted tree or match list
  */
 export function directoryTree(dirPath, opts = {}) {
+    if (opts.pattern) return findByPattern(dirPath, opts);
+
     const compact = opts.format === "compact";
     const maxDepth = compact ? 1 : (opts.max_depth ?? 3);
     const useGitignore = opts.gitignore ?? true;

package/output-style.md

@@ -0,0 +1,27 @@
+---
+name: hex-line
+description: Prefer hex-line MCP tools over built-in Read/Edit/Write/Grep
+keep-coding-instructions: true
+---
+
+# MCP Tool Preferences
+
+When `hex-line` MCP is available, **always prefer it** over built-in file tools:
+
+| Instead of | Use | Why |
+|-----------|-----|-----|
+| Read | `mcp__hex-line__read_file` | Hash-annotated, edit-ready |
+| Edit | `mcp__hex-line__edit_file` | Hash-verified anchors |
+| Write | `mcp__hex-line__write_file` | Consistent workflow |
+| Grep | `mcp__hex-line__grep_search` | Hash-annotated matches |
+
+## Efficient File Reading
+
+For code files >100 lines, ALWAYS:
+1. `outline` first (10-20 lines of structure)
+2. `read_file` with offset/limit for the specific section you need
+
+NEVER read a large file in full — outline+targeted read saves 75% tokens.
+
+Bash OK for: npm/node/git/docker/curl, pipes, compound commands.
+**Exceptions** (use built-in Read): images, PDFs, Jupyter notebooks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levnikolaevich/hex-line-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "Hash-verified file editing MCP + token efficiency hook for AI coding agents. 11 tools: read, edit, write, grep, outline, verify, directory_tree, file_info, setup_hooks, changes, bulk_replace.",
   "main": "server.mjs",
@@ -12,7 +12,8 @@
     "hook.mjs",
     "benchmark.mjs",
     "lib/",
-    "README.md"
+    "README.md",
+    "output-style.md"
   ],
   "scripts": {
     "start": "node server.mjs",