@levnikolaevich/hex-line-mcp 1.6.0 → 1.8.0

package/README.md

@@ -11,7 +11,7 @@ Every line carries an FNV-1a content hash. Every edit must present those hashes
 
 ## Features
 
-### 11 MCP Tools
+### 10 MCP Tools
 
 Core day-to-day tools:
 
@@ -28,7 +28,6 @@ Advanced / occasional:
 - `directory_tree`
 - `get_file_info`
 - `changes`
-- `setup_hooks`
 
 | Tool | Description | Key Feature |
 |------|-------------|-------------|
@@ -40,7 +39,6 @@ Advanced / occasional:
 | `verify` | Check if held checksums / revision are still current | Staleness check without full re-read |
 | `directory_tree` | Compact directory tree with root .gitignore support | Skips node_modules/.git, shows file sizes |
 | `get_file_info` | File metadata without reading content | Size, lines, mtime, type, binary detection |
-| `setup_hooks` | Configure Claude hooks + install output style | Gemini/Codex get guidance only; no hooks |
 | `changes` | Compare file against git ref, shows added/removed/modified symbols | AST-level semantic diff |
 | `bulk_replace` | Search-and-replace across multiple files by glob | Compact summary (default) or capped diffs via `format`, dry_run, max_files |
 
@@ -70,23 +68,9 @@ ripgrep is bundled via `@vscode/ripgrep` — no manual install needed for `grep_
 
 ### Hooks
 
-Automatic setup (run once after MCP install):
+Hooks and output style are auto-synced on every MCP server startup. The server compares installed files with bundled versions and updates only when content differs. First run after `npm i -g` triggers full install automatically.
 
-```
-mcp__hex-line__setup_hooks(agent="claude")
-```
-
-Hooks are written to global `~/.claude/settings.json` with absolute path to `hook.mjs` from the global npm install. Manual configuration is not needed.
-
-### Output Style
-
-Optional: install a persistent Output Style that embeds tool preferences directly in Claude's system prompt. Reduces hook firings by making Claude prefer hex-line tools from the start.
-
-```
-mcp__hex-line__setup_hooks(agent="claude")
-```
-
-The `setup_hooks` tool automatically installs the output style to `~/.claude/output-styles/hex-line.md` and activates it if no other style is set. To activate manually: `/config` > Output style > hex-line.
+Hooks are written to global `~/.claude/settings.json` with absolute path to `hook.mjs`. Output style is installed to `~/.claude/output-styles/hex-line.md` and activated if no other style is set. To activate manually: `/config` > Output style > hex-line.
 
 ## Validation
 

package/dist/hook.mjs

@@ -89,6 +89,28 @@ var BINARY_EXT = /* @__PURE__ */ new Set([
   ".woff",
   ".woff2"
 ]);
+var OUTLINEABLE_EXT = /* @__PURE__ */ new Set([
+  ".js",
+  ".mjs",
+  ".cjs",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".py",
+  ".go",
+  ".rs",
+  ".java",
+  ".c",
+  ".h",
+  ".cpp",
+  ".cs",
+  ".rb",
+  ".php",
+  ".kt",
+  ".swift",
+  ".sh",
+  ".bash"
+]);
 var REVERSE_TOOL_HINTS = {
   "mcp__hex-line__read_file": "Read (file_path, offset, limit)",
   "mcp__hex-line__edit_file": "Edit (old_string, new_string, replace_all)",
@@ -99,8 +121,7 @@ var REVERSE_TOOL_HINTS = {
   "mcp__hex-line__outline": "Read with offset/limit",
   "mcp__hex-line__verify": "Read (re-read file to check freshness)",
   "mcp__hex-line__changes": "Bash(git diff)",
-  "mcp__hex-line__bulk_replace": "Edit (text rename/refactor across files)",
-  "mcp__hex-line__setup_hooks": "Not available (hex-line disabled)"
+  "mcp__hex-line__bulk_replace": "Edit (text rename/refactor across files)"
 };
 var TOOL_HINTS = {
   Read: "mcp__hex-line__read_file (not Read). For writing: write_file (no prior Read needed)",
@@ -118,8 +139,7 @@ var TOOL_HINTS = {
   outline: "mcp__hex-line__outline (before reading large code files)",
   verify: "mcp__hex-line__verify (staleness / revision check without re-read)",
   changes: "mcp__hex-line__changes (git diff with change symbols)",
-  bulk: "mcp__hex-line__bulk_replace (multi-file search-replace)",
-  setup: "mcp__hex-line__setup_hooks (configure hooks for agents)"
+  bulk: "mcp__hex-line__bulk_replace (multi-file search-replace)"
 };
 var BASH_REDIRECTS = [
   { regex: /^cat\s+\S+/, key: "cat" },
@@ -183,7 +203,7 @@ var CMD_PATTERNS = [
 var LINE_THRESHOLD = 50;
 var HEAD_LINES = 15;
 var TAIL_LINES = 15;
-var LARGE_FILE_BYTES = 15 * 1024;
+var LARGE_FILE_BYTES = 5 * 1024;
 var LARGE_EDIT_CHARS = 1200;
 function extOf(filePath) {
   const dot = filePath.lastIndexOf(".");
@@ -250,28 +270,47 @@ function isHexLineDisabled(configPath) {
 function _resetHexLineDisabledCache() {
   _hexLineDisabled = null;
 }
+var _hookMode;
+function getHookMode() {
+  if (_hookMode !== void 0) return _hookMode;
+  _hookMode = "blocking";
+  try {
+    const stateFile = resolve(process.cwd(), ".hex-skills/environment_state.json");
+    const data = JSON.parse(readFileSync(stateFile, "utf-8"));
+    if (data.hooks?.mode === "advisory") _hookMode = "advisory";
+  } catch {
+  }
+  return _hookMode;
+}
 function block(reason, context) {
   const output = {
     hookSpecificOutput: {
-      hookEventName: "PreToolUse",
-      permissionDecision: "deny",
-      permissionDecisionReason: reason
-    }
+      permissionDecision: "deny"
+    },
+    systemMessage: context ? `${reason}
+${context}` : reason
   };
-  if (context) output.hookSpecificOutput.additionalContext = context;
   process.stdout.write(JSON.stringify(output));
   process.exit(2);
 }
-function advise(reason) {
-  process.stdout.write(JSON.stringify({
+function advise(reason, context) {
+  const output = {
     hookSpecificOutput: {
-      hookEventName: "PreToolUse",
-      permissionDecision: "approve",
-      permissionDecisionReason: reason
-    }
-  }));
+      permissionDecision: "allow"
+    },
+    systemMessage: context ? `${reason}
+${context}` : reason
+  };
+  process.stdout.write(JSON.stringify(output));
   process.exit(0);
 }
+function redirect(reason, context) {
+  if (getHookMode() === "advisory") {
+    advise(reason, context);
+  } else {
+    block(reason, context);
+  }
+}
 function handlePreToolUse(data) {
   const toolName = data.tool_name || "";
   const toolInput = data.tool_input || {};
@@ -309,10 +348,13 @@ function handlePreToolUse(data) {
         process.exit(0);
       }
       if (fileSize !== null && fileSize <= LARGE_FILE_BYTES) {
-        advise("hex-line read_file returns hash-annotated lines for verified edit workflow. For code files, outline gives a compact structural map first.");
+        const ext2 = filePath ? extOf(filePath) : "";
+        const hint = filePath && OUTLINEABLE_EXT.has(ext2) ? `mcp__hex-line__outline(path="${filePath}") gives a compact structural map. For edits, use mcp__hex-line__read_file(path="${filePath}") with ranges.` : filePath ? `NEXT READ: use mcp__hex-line__read_file(path="${filePath}"). Built-in Read allowed this time but wastes edit context.` : "NEXT READ: use mcp__hex-line__read_file. Built-in Read allowed this time but wastes edit context.";
+        advise(hint);
       }
-      const target = filePath ? `Use mcp__hex-line__outline or mcp__hex-line__read_file with path="${filePath}"` : "Use mcp__hex-line__directory_tree or mcp__hex-line__read_file";
-      block(target, "For large or unknown full reads: call outline first, then read_file with offset/limit or ranges. Do not use built-in Read here.");
+      const ext = filePath ? extOf(filePath) : "";
+      const outlineHint = filePath && OUTLINEABLE_EXT.has(ext) ? `Use mcp__hex-line__outline(path="${filePath}") for structure, then mcp__hex-line__read_file(path="${filePath}") with ranges to read only what you need.` : filePath ? `Use mcp__hex-line__read_file(path="${filePath}") with ranges or offset/limit` : "Use mcp__hex-line__directory_tree or mcp__hex-line__read_file";
+      redirect(outlineHint, "Do not use built-in Read for full reads of large files.");
     }
     if (toolName === "Edit") {
       const oldText = String(toolInput.old_string || "");
@@ -321,15 +363,15 @@ function handlePreToolUse(data) {
         process.exit(0);
       }
       const target = filePath ? `Use mcp__hex-line__grep_search or mcp__hex-line__read_file, then mcp__hex-line__edit_file with path="${filePath}"` : "Use mcp__hex-line__grep_search or mcp__hex-line__read_file, then mcp__hex-line__edit_file";
-      block(target, "For large or repeated edits: locate anchors/checksums first, then call edit_file once with batched edits.");
+      redirect(target, "For large or repeated edits: locate anchors/checksums first, then call edit_file once with batched edits.");
     }
     if (toolName === "Write") {
       const pathNote = filePath ? ` with path="${filePath}"` : "";
-      block(`Use mcp__hex-line__write_file${pathNote}`, TOOL_HINTS.Write);
+      redirect(`Use mcp__hex-line__write_file${pathNote}`, TOOL_HINTS.Write);
     }
     if (toolName === "Grep") {
       const pathNote = filePath ? ` with path="${filePath}"` : "";
-      block(`Use mcp__hex-line__grep_search${pathNote}`, TOOL_HINTS.Grep);
+      redirect(`Use mcp__hex-line__grep_search${pathNote}`, TOOL_HINTS.Grep);
     }
   }
   if (toolName === "Bash") {
@@ -352,7 +394,7 @@ function handlePreToolUse(data) {
         if (regex.test(firstCmd)) {
           const hint = TOOL_HINTS[key];
           const toolName2 = hint.split(" (")[0];
-          block(`Use ${toolName2} instead of piped command`, hint);
+          redirect(`Use ${toolName2} instead of piped command`, hint);
         }
       }
       process.exit(0);
@@ -363,7 +405,7 @@ function handlePreToolUse(data) {
         const toolName2 = hint.split(" (")[0];
         const args = command.split(/\s+/).slice(1).join(" ");
         const argsNote = args ? ` \u2014 args: "${args}"` : "";
-        block(`Use ${toolName2}${argsNote}`, hint);
+        redirect(`Use ${toolName2}${argsNote}`, hint);
       }
     }
   }
@@ -441,7 +483,8 @@ function handleSessionStart() {
   process.stdout.write(JSON.stringify({ systemMessage: msg }));
   process.exit(0);
 }
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+var _norm = (p) => p.replace(/\\/g, "/");
+if (_norm(process.argv[1]) === _norm(fileURLToPath(import.meta.url))) {
   let input = "";
   process.stdin.on("data", (chunk) => {
     input += chunk;

package/dist/server.mjs

@@ -483,7 +483,7 @@ function parseChecksum(cs) {
 // lib/snapshot.mjs
 var MAX_FILES = 200;
 var MAX_REVISIONS_PER_FILE = 5;
-var TTL_MS = 5 * 60 * 1e3;
+var TTL_MS = 15 * 60 * 1e3;
 var latestByFile = /* @__PURE__ */ new Map();
 var revisionsById = /* @__PURE__ */ new Map();
 var fileRevisionIds = /* @__PURE__ */ new Map();
@@ -2425,6 +2425,8 @@ var __filename = fileURLToPath(import.meta.url);
 var __dirname = dirname3(__filename);
 var SOURCE_HOOK = resolve6(__dirname, "..", "hook.mjs");
 var DIST_HOOK = resolve6(__dirname, "hook.mjs");
+var SOURCE_STYLE = resolve6(__dirname, "..", "output-style.md");
+var INSTALLED_STYLE = resolve6(homedir(), ".claude", "output-styles", "hex-line.md");
 var HOOK_SIGNATURE = "hex-line";
 var CLAUDE_HOOKS = {
   SessionStart: {
@@ -2455,16 +2457,19 @@ function findEntryByCommand(entries) {
     )
   );
 }
-function writeHooksToFile(settingsPath, label) {
-  const config = readJson(settingsPath) || {};
-  if (!config.hooks || typeof config.hooks !== "object") {
-    config.hooks = {};
+function safeRead(filePath) {
+  try {
+    return readFileSync3(filePath, "utf-8");
+  } catch {
+    return null;
   }
+}
+function writeHooksToFile(settingsPath) {
+  const config = readJson(settingsPath) || {};
+  if (!config.hooks || typeof config.hooks !== "object") config.hooks = {};
   let changed = false;
   for (const [event, desired] of Object.entries(CLAUDE_HOOKS)) {
-    if (!Array.isArray(config.hooks[event])) {
-      config.hooks[event] = [];
-    }
+    if (!Array.isArray(config.hooks[event])) config.hooks[event] = [];
     const entries = config.hooks[event];
     const idx = findEntryByCommand(entries);
     if (idx >= 0) {
@@ -2483,116 +2488,60 @@ function writeHooksToFile(settingsPath, label) {
     config.disableAllHooks = false;
     changed = true;
   }
-  if (!changed) {
-    return `Claude (${label}): already configured`;
-  }
-  writeJson(settingsPath, config);
-  return `Claude (${label}): hooks -> ${STABLE_HOOK_PATH} OK`;
+  if (changed) writeJson(settingsPath, config);
+  return changed;
 }
 function cleanLocalHooks() {
   const localPath = resolve6(process.cwd(), ".claude/settings.local.json");
   const config = readJson(localPath);
-  if (!config || !config.hooks || typeof config.hooks !== "object") {
-    return "local: clean";
-  }
+  if (!config || !config.hooks || typeof config.hooks !== "object") return;
   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);
+    const idx = findEntryByCommand(config.hooks[event]);
     if (idx >= 0) {
-      entries.splice(idx, 1);
+      config.hooks[event].splice(idx, 1);
       changed = true;
     }
-    if (entries.length === 0) {
-      delete config.hooks[event];
-    }
-  }
-  if (Object.keys(config.hooks).length === 0) {
-    delete config.hooks;
+    if (config.hooks[event].length === 0) delete config.hooks[event];
   }
-  if (!changed) {
-    return "local: clean";
-  }
-  writeJson(localPath, config);
-  return "local: removed old hex-line hooks";
-}
-function installOutputStyle() {
-  const source = resolve6(dirname3(fileURLToPath(import.meta.url)), "..", "output-style.md");
-  const target = resolve6(homedir(), ".claude", "output-styles", "hex-line.md");
-  mkdirSync(dirname3(target), { recursive: true });
-  writeFileSync2(target, readFileSync3(source, "utf-8"), "utf-8");
+  if (Object.keys(config.hooks).length === 0) delete config.hooks;
+  if (changed) writeJson(localPath, config);
+}
+function syncOutputStyle() {
+  const source = safeRead(SOURCE_STYLE);
+  if (!source) return false;
+  const installed = safeRead(INSTALLED_STYLE);
+  if (installed === source) return false;
+  mkdirSync(dirname3(INSTALLED_STYLE), { recursive: true });
+  writeFileSync2(INSTALLED_STYLE, source, "utf-8");
   const userSettings = resolve6(homedir(), ".claude/settings.json");
   const config = readJson(userSettings) || {};
-  const prev = config.outputStyle;
-  if (!prev) {
+  if (!config.outputStyle) {
     config.outputStyle = "hex-line";
     writeJson(userSettings, config);
   }
-  const msg = prev ? `Output style file installed. Existing style '${prev}' preserved (not overridden)` : "Output style 'hex-line' installed and activated globally";
-  return msg;
+  return true;
 }
-function setupClaude() {
-  const results = [];
+function autoSync() {
   const hookSource = existsSync5(DIST_HOOK) ? DIST_HOOK : SOURCE_HOOK;
-  if (!existsSync5(hookSource)) {
-    return "Claude: FAILED \u2014 hook.mjs not found. Reinstall @levnikolaevich/hex-line-mcp.";
-  }
-  mkdirSync(STABLE_HOOK_DIR, { recursive: true });
-  copyFileSync(hookSource, STABLE_HOOK_PATH);
-  results.push(`hook.mjs -> ${STABLE_HOOK_PATH}`);
-  const globalPath = resolve6(homedir(), ".claude/settings.json");
-  results.push(writeHooksToFile(globalPath, "global"));
-  results.push(cleanLocalHooks());
-  results.push(installOutputStyle());
-  return results.join(" | ");
-}
-function setupGemini() {
-  return "Gemini: Not supported (Gemini CLI does not support hooks. Add MCP Tool Preferences to GEMINI.md instead)";
-}
-function setupCodex() {
-  return "Codex: Not supported (Codex CLI does not support hooks. Add MCP Tool Preferences to AGENTS.md instead)";
-}
-function uninstallClaude() {
+  if (!existsSync5(hookSource)) return;
+  const changes = [];
+  const srcHook = safeRead(hookSource);
+  const dstHook = safeRead(STABLE_HOOK_PATH);
+  if (srcHook && srcHook !== dstHook) {
+    mkdirSync(STABLE_HOOK_DIR, { recursive: true });
+    copyFileSync(hookSource, STABLE_HOOK_PATH);
+    changes.push("hook");
+  }
+  if (syncOutputStyle()) changes.push("style");
   const globalPath = resolve6(homedir(), ".claude/settings.json");
-  const config = readJson(globalPath);
-  if (!config || !config.hooks || typeof config.hooks !== "object") {
-    return "Claude: no hooks to remove";
-  }
-  let changed = false;
-  for (const event of Object.keys(CLAUDE_HOOKS)) {
-    if (!Array.isArray(config.hooks[event])) continue;
-    const idx = findEntryByCommand(config.hooks[event]);
-    if (idx >= 0) {
-      config.hooks[event].splice(idx, 1);
-      if (config.hooks[event].length === 0) delete config.hooks[event];
-      changed = true;
-    }
-  }
-  if (Object.keys(config.hooks).length === 0) delete config.hooks;
-  if (!changed) return "Claude: no hex-line hooks found";
-  writeJson(globalPath, config);
-  return "Claude: hex-line hooks removed from global settings";
-}
-var AGENTS = { claude: setupClaude, gemini: setupGemini, codex: setupCodex };
-function setupHooks(agent = "all", action = "install") {
-  const target = (agent || "all").toLowerCase();
-  const act = (action || "install").toLowerCase();
-  if (act === "uninstall") {
-    const result = uninstallClaude();
-    return `Hooks uninstalled:
-  ${result}
-
-Restart Claude Code to apply changes.`;
-  }
-  if (target !== "all" && !AGENTS[target]) {
-    throw new Error(`UNKNOWN_AGENT: '${agent}'. Supported: claude, gemini, codex, all`);
+  if (writeHooksToFile(globalPath)) changes.push("settings");
+  cleanLocalHooks();
+  if (changes.length > 0) {
+    process.stderr.write(`hex-line: synced ${changes.join(", ")}
+`);
   }
-  const targets = target === "all" ? Object.keys(AGENTS) : [target];
-  const results = targets.map((name) => "  " + AGENTS[name]());
-  const header = `Hooks configured for ${target}:`;
-  const footer = "\nRestart Claude Code to apply hook changes.";
-  return [header, ...results, footer].join("\n");
 }
 
 // lib/changes.mjs
@@ -2837,7 +2786,7 @@ OUTPUT_CAPPED: Output exceeded ${MAX_BULK_OUTPUT_CHARS} chars.`;
 }
 
 // server.mjs
-var version = true ? "1.6.0" : (await null).createRequire(import.meta.url)("./package.json").version;
+var version = true ? "1.8.0" : (await null).createRequire(import.meta.url)("./package.json").version;
 var { server, StdioServerTransport } = await createServerRuntime({
   name: "hex-line-mcp",
   version
@@ -3086,22 +3035,6 @@ server.registerTool("get_file_info", {
     return { content: [{ type: "text", text: e.message }], isError: true };
   }
 });
-server.registerTool("setup_hooks", {
-  title: "Setup Hooks",
-  description: "Install or uninstall hex-line hooks in CLI agent settings. Idempotent.",
-  inputSchema: z2.object({
-    agent: z2.string().optional().describe('Target agent: "claude", "gemini", "codex", or "all" (default: "all")'),
-    action: z2.string().optional().describe('"install" (default) or "uninstall"')
-  }),
-  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true }
-}, async (rawParams) => {
-  const { agent, action } = coerceParams(rawParams);
-  try {
-    return { content: [{ type: "text", text: setupHooks(agent, action) }] };
-  } catch (e) {
-    return { content: [{ type: "text", text: e.message }], isError: true };
-  }
-});
 server.registerTool("changes", {
   title: "Semantic Diff",
   description: "Compare file or directory against git ref (default: HEAD). Shows added/removed/modified symbols or file stats.",
@@ -3155,3 +3088,7 @@ server.registerTool("bulk_replace", {
 var transport = new StdioServerTransport();
 await server.connect(transport);
 void checkForUpdates("@levnikolaevich/hex-line-mcp", version);
+try {
+  autoSync();
+} catch {
+}

package/output-style.md

@@ -36,7 +36,8 @@ Prefer:
 2. send one `edit_file` call with batched edits
 3. carry `revision` from `read_file` into `base_revision` on follow-up edits
 4. use `set_line`, `replace_lines`, `insert_after`, `replace_between` based on scope
-5. use `verify` before rereading after staleness
+5. if edit returns CONFLICT, call `verify` with stale checksum — it reports VALID/STALE/INVALID without rereading the whole file
+6. only reread (`read_file`) when `verify` confirms STALE
 
 Post-edit output uses `block: post_edit` with checksum — use it directly for follow-up edits or verify.
 
@@ -45,6 +46,20 @@ Avoid:
 - full-file rewrites for local changes
 - using `bulk_replace` for structural block rewrites
 
+
+## hex-graph — Code Analysis
+
+Run `index_project` once per session before using other graph tools.
+
+| Task | Tool | Output |
+|------|------|--------|
+| Refactoring / moving code | `find_references`, `find_implementations` | All usages + implementations |
+| Code review / tech debt | `find_cycles`, `find_hotspots` | Circular deps, complexity hotspots |
+| Dead code cleanup | `find_unused_exports` | Exports nobody imports |
+| Architecture overview | `get_architecture`, `get_module_metrics` | Module map + coupling metrics |
+| Duplicate detection | `find_clones` | Similar code blocks |
+| Impact analysis | `trace_paths` | Call chains A → B |
+| Symbol lookup | `search_symbols`, `get_symbol` | Find by name, get details |
 # Response Style
 
 Keep responses compact and operational. Explain only what is needed to complete the task or justify a non-obvious decision.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@levnikolaevich/hex-line-mcp",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "mcpName": "io.github.levnikolaevich/hex-line-mcp",
   "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.",
+  "description": "Hash-verified file editing MCP + token efficiency hook for AI coding agents. 10 tools: read, edit, write, grep, outline, verify, directory_tree, file_info, changes, bulk_replace.",
   "main": "dist/server.mjs",
   "bin": {
     "hex-line-mcp": "dist/server.mjs"