Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

docs(examples): add hooks-sync walkthrough (#1386)

Felix-Ayush40b2d5082b99
diff --git a/examples/README.md b/examples/README.md
index 34aebe5c5..b9bf26788 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -10,6 +10,7 @@ self-contained README under `examples/<name>/`.
| [codex/](codex/) | Codex CLI setup: `repowise init --codex`, smoke checks, local plugin install |
| [distill/](distill/) | `distill` / `expand` / `saved` — compress command output (no LLM key) |
| [health-coverage/](health-coverage/) | Code health, coverage ingest, and impacted-tests (no LLM key) |
+| [hooks-sync/](hooks-sync/) | `hook install` + `watch` — keep the index fresh (no LLM key) |
| [opencode/](opencode/) | OpenCode as the LLM provider for wiki generation |
| [risk/](risk/) | `repowise risk` change / PR defect scoring (no LLM key) |
| [search/](search/) | `repowise search` fulltext / symbol / semantic wiki lookup |
@@ -34,5 +35,6 @@ self-contained README under `examples/<name>/`.
- [Change risk](../docs/layers/CHANGE_RISK.md)
- [Test intelligence](../docs/layers/TEST_INTELLIGENCE.md)
- [Distill](../docs/agent/DISTILL.md)
+- [Auto-sync](../docs/scale/AUTO_SYNC.md)
- [Structurizr export](../docs/architecture/structurizr-export.md)
- [CLI: security](../docs/reference/CLI_REFERENCE.md)
diff --git a/examples/hooks-sync/README.md b/examples/hooks-sync/README.md
new file mode 100644
index 000000000..54b16e5ed
--- /dev/null
+++ b/examples/hooks-sync/README.md
@@ -0,0 +1,70 @@
+# Hooks & Auto-Sync Example
+
+Keep the wiki index fresh with `repowise hook` (post-commit) and
+`repowise watch` (file watcher). No LLM key required when you pass
+`--index-only` to the underlying update.
+
+## Prerequisites
+
+1. A git repository with `repowise init` already run once.
+2. `repowise` on `PATH` (`uv tool install repowise` or from this repo:
+ `uv sync --all-packages`).
+
+```bash
+cd /path/to/your-repo
+repowise init --index-only --yes
+```
+
+## 1. Post-commit hook
+
+Install a hook that runs `repowise update` in the background after each
+commit:
+
+```bash
+repowise hook install
+repowise hook status # ✓ post-commit when installed
+repowise hook uninstall # remove when you no longer want it
+```
+
+In a workspace, install across every repo:
+
+```bash
+repowise hook install --workspace
+repowise hook status --workspace
+```
+
+## 2. File watcher (uncommitted work)
+
+`watch` re-indexes on save — staged, unstaged, and untracked files — which
+the post-commit hook does not cover:
+
+```bash
+repowise watch --index-only # no model calls per save
+repowise watch --debounce 5000 # wait 5s after last change
+repowise watch --workspace --index-only
+```
+
+Press `Ctrl+C` to stop the watcher.
+
+## 3. Agent hook telemetry (optional)
+
+If you use Claude Code agent hooks, inspect what fired:
+
+```bash
+repowise hook stats
+repowise hook stats --json
+```
+
+## Smoke checklist
+
+| Step | Expected |
+|------|----------|
+| `repowise hook status` | Shows installed / not installed for post-commit |
+| `repowise hook install` then `hook status` | `✓ post-commit: installed` |
+| `repowise hook uninstall` then `hook status` | `✗ post-commit: not installed` |
+
+## Related docs
+
+- [Auto-sync](../../docs/scale/AUTO_SYNC.md)
+- [Agent hooks](../../docs/agent/HOOKS.md)
+- [CLI: hook / watch](../../docs/reference/CLI_REFERENCE.md)