From 73753bbf8a773336223084841fce47e669affc16 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 09:36:58 +0000 Subject: [PATCH 1/2] docs(onboarding): refresh the graph from hooks instead of a watcher (#175) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FuX9kDSsfALRNYaDsKN4K6 --- docs/how-to/AGENT_ONBOARDING.md | 41 +++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/how-to/AGENT_ONBOARDING.md b/docs/how-to/AGENT_ONBOARDING.md index 4366d345..72ee1632 100644 --- a/docs/how-to/AGENT_ONBOARDING.md +++ b/docs/how-to/AGENT_ONBOARDING.md @@ -67,6 +67,47 @@ symbol was added, renamed or removed. It never creates a missing database, and a graph ingested before this option existed is only reported stale, not refreshed, until it is ingested once more. +### Refreshing outside the MCP server: hooks, not a watcher + +cgis has no watch mode, on purpose (#175). A watcher re-ingests on every save, +and an agent's multi-file edit is a burst of saves, each of which can cost a +full rebuild; the graph only needs to be current when something reads it. If +you query from the CLI, or want the graph current before the agent's next +turn, hang an incremental ingest on an event that ends a burst instead. Use the +same `--source-root`/`--domains` the graph was built with. + +**Claude Code** — once per finished turn, not once per edit +(`.claude/settings.json`): + +```json +{ + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "command", + "command": "cd \"$CLAUDE_PROJECT_DIR\" && cgis ingest . -o graph.db -i >/dev/null 2>&1 || true" + } + ] + } + ] + } +} +``` + +**git** — after a checkout, pull or rebase swaps many files at once +(`.git/hooks/post-checkout`, and the same body in `post-merge` and +`post-rewrite`; make each executable): + +```sh +#!/bin/sh +cgis ingest . -o graph.db -i >/dev/null 2>&1 || true +``` + +`|| true` keeps a failed ingest from failing the hook; the read commands will +still say the graph is stale. + --- ## Step 3: Available MCP tools From 40ffee93e75b443bb5905aa2031adfe820d720ba Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 09:38:40 +0000 Subject: [PATCH 2/2] docs(onboarding): hooks ingest the same path as Step 1 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01FuX9kDSsfALRNYaDsKN4K6 --- docs/how-to/AGENT_ONBOARDING.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/how-to/AGENT_ONBOARDING.md b/docs/how-to/AGENT_ONBOARDING.md index 72ee1632..338567c1 100644 --- a/docs/how-to/AGENT_ONBOARDING.md +++ b/docs/how-to/AGENT_ONBOARDING.md @@ -74,7 +74,8 @@ and an agent's multi-file edit is a burst of saves, each of which can cost a full rebuild; the graph only needs to be current when something reads it. If you query from the CLI, or want the graph current before the agent's next turn, hang an incremental ingest on an event that ends a burst instead. Use the -same `--source-root`/`--domains` the graph was built with. +same path and `--source-root`/`--domains` the graph was built with (`./src` +as in Step 1); a different path renames every node. **Claude Code** — once per finished turn, not once per edit (`.claude/settings.json`): @@ -87,7 +88,7 @@ same `--source-root`/`--domains` the graph was built with. "hooks": [ { "type": "command", - "command": "cd \"$CLAUDE_PROJECT_DIR\" && cgis ingest . -o graph.db -i >/dev/null 2>&1 || true" + "command": "cd \"$CLAUDE_PROJECT_DIR\" && cgis ingest ./src -o graph.db -i >/dev/null 2>&1 || true" } ] } @@ -102,7 +103,7 @@ same `--source-root`/`--domains` the graph was built with. ```sh #!/bin/sh -cgis ingest . -o graph.db -i >/dev/null 2>&1 || true +cgis ingest ./src -o graph.db -i >/dev/null 2>&1 || true ``` `|| true` keeps a failed ingest from failing the hook; the read commands will