Agent hooks keep the navegador graph in sync as AI coding agents work. Without hooks, the graph goes stale the moment an agent edits a file. With hooks, the graph is re-ingested automatically after every file write, and architectural decisions in `DECISIONS.md` are synced into the knowledge layer.
4
5
---
6
7
## Why hooks
8
9
A stale graph gives wrong answers. If an agent adds a new function and then asks `navegador function` about a caller, the graph needs to reflect the edit. Hooks solve this by triggering `navegador ingest` on the modified files immediately after the agent writes them.
10
11
Hooks also enforce the habit: every agent session starts with the graph as ground truth, not a stale snapshot.
12
13
---
14
15
## Claude Code
16
17
### Install
18
19
The hook file lives at `.claude/hooks/claude-hook.py`. Bootstrap installs it automatically:
20
21
```bash
22
./bootstrap.sh --repo owner/repo --agent claude
23
```
24
25
To install manually, copy `hooks/claude-hook.py` from the navegador repo into your project's `.claude/hooks/` directory.
26
27
### settings.json config
28
29
In your project's `.claude/settings.json`, register the hook:
30
31
```json
32
{
33
"hooks": {
34
"PostToolUse": [
35
{
36
"matcher": "Write|Edit|MultiEdit",
37
"hooks": [
38
{
39
"type": "command",
40
"command": "python .claude/hooks/claude-hook.py"
41
}
42
]
43
}
44
]
45
}
46
}
47
```
48
49
### What the hook does
50
51
On every `Write`, `Edit`, or `MultiEdit` tool call:
52
53
1. Reads the list of modified file paths from the tool result
54
2. Runs `navegador ingest` scoped to those files (fast incremental update)
55
3. Checks for changes to `DECISIONS.md` — if found, syncs any new ADR entries into the graph as `Decision` nodes
56
4. Logs a one-line summary to stderr (visible in Claude's tool output)
57
58
---
59
60
## Gemini CLI
61
62
### Install
63
64
The hook file lives at `.gemini/hooks/gemini-hook.py`. Bootstrap installs it automatically:
65
66
```bash
67
./bootstrap.sh --repo owner/repo --agent gemini
68
```
69
70
To install manually, copy `hooks/gemini-hook.py` from the navegador repo into your project's `.gemini/hooks/` directory.
71
72
### GEMINI.md config
73
74
Add to your project's `GEMINI.md`:
75
76
```markdown
77
## Tool Hooks
78
79
After writing or editing any source file, run:
80
```
81
python .gemini/hooks/gemini-hook.py <file_path>
82
```
83
84
This keeps the navegador knowledge graph in sync. The graph is your source of truth for code structure and project decisions.
85
```
86
87
The Gemini CLI does not have a declarative hook registry like Claude. The `GEMINI.md` instruction tells the model to call the hook script explicitly as a tool after file writes.
88
89
---
90
91
## OpenAI
92
93
OpenAI agents use a dispatcher script and a tool definition JSON file.
94
95
### Install
96
97
```bash
98
./bootstrap.sh --repo owner/repo --agent openai
99
```
100
101
This places:
102
- `openai-hook.py` — dispatcher script
103
- `openai-tools.json` — tool schema for the OpenAI function-calling API
104
105
### openai-tools.json
106
107
The tool schema exposes navegador commands as callable functions:
108
109
```json
110
[
111
{
112
"type": "function",
113
"function": {
114
"name": "navegador_explain",
115
"description": "Look up any code or knowledge node by name",
116
"parameters": {
117
"type": "object",
118
"properties": {
119
"name": { "type": "string", "description": "Node name to explain" },