From 441745c12460f58a7c92bcec1aab2df25c08e068 Mon Sep 17 00:00:00 2001 From: jarvisai1909 Date: Sun, 26 Apr 2026 13:06:15 +0800 Subject: [PATCH] docs: clarify PostToolUse hook is notification-only, not auto-reindex (#1070) --- .claude/skills/gitnexus/gitnexus-cli/SKILL.md | 2 +- AGENTS.md | 2 +- README.md | 2 +- gitnexus/skills/gitnexus-cli.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.claude/skills/gitnexus/gitnexus-cli/SKILL.md b/.claude/skills/gitnexus/gitnexus-cli/SKILL.md index 499bfb932..24586205e 100644 --- a/.claude/skills/gitnexus/gitnexus-cli/SKILL.md +++ b/.claude/skills/gitnexus/gitnexus-cli/SKILL.md @@ -23,7 +23,7 @@ Run from the project root. This parses all source files, builds the knowledge gr | `--embeddings` | Enable embedding generation for semantic search (off by default) | | `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them. | -**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated. +**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook detects staleness after `git commit` and `git merge` and notifies the agent to run `analyze` — the hook does not run analyze itself, to avoid blocking the agent for up to 120s and risking KuzuDB corruption on timeout. ### status — Check index freshness diff --git a/AGENTS.md b/AGENTS.md index 8e2fa4610..cf8cc9cd6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -155,7 +155,7 @@ npx gitnexus analyze --drop-embeddings # explicit opt-in to wipe existing embed Check `.gitnexus/meta.json` `stats.embeddings` (0 = none). A plain `analyze` no longer drops existing vectors — pass `--drop-embeddings` to wipe. -> Claude Code: PostToolUse hook handles this after `git commit` and `git merge`. +> Claude Code: PostToolUse hook detects a stale index after `git commit` and `git merge` and prompts the agent to run `analyze`. The hook does not invoke `analyze` itself. ## CLI Skills diff --git a/README.md b/README.md index a31a707dd..33803413b 100644 --- a/README.md +++ b/README.md @@ -120,7 +120,7 @@ To configure MCP for your editor, run `npx gitnexus setup` once — or set it up | **Windsurf** | Yes | — | — | MCP | | **OpenCode** | Yes | Yes | — | MCP + Skills | -> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that enrich searches with graph context + PostToolUse hooks that auto-reindex after commits. +> **Claude Code** gets the deepest integration: MCP tools + agent skills + PreToolUse hooks that enrich searches with graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex. ## Community Integrations diff --git a/gitnexus/skills/gitnexus-cli.md b/gitnexus/skills/gitnexus-cli.md index a10104aef..cd9a83be0 100644 --- a/gitnexus/skills/gitnexus-cli.md +++ b/gitnexus/skills/gitnexus-cli.md @@ -23,7 +23,7 @@ Run from the project root. This parses all source files, builds the knowledge gr | `--embeddings` | Enable embedding generation for semantic search (off by default) | | `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them. | -**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook runs `analyze` automatically after `git commit` and `git merge`, preserving embeddings if previously generated. +**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Claude Code, a PostToolUse hook detects staleness after `git commit` and `git merge` and notifies the agent to run `analyze` — the hook does not run analyze itself, to avoid blocking the agent for up to 120s and risking KuzuDB corruption on timeout. ### status — Check index freshness