This guide walks from a fresh install to a fully wired agent integration in five steps.
4
5
---
6
7
## Step 1: Install
8
9
```bash
10
pip install navegador
11
navegador --version
12
```
13
14
Python 3.12+ is required. For additional languages (Kotlin, C#, PHP, Ruby, Swift, C, C++) install the `[languages]` extra. See [Installation](installation.md) for all extras and Redis setup.
15
16
---
17
18
## Step 2: Ingest a repo
19
20
Point navegador at any local source tree:
21
22
```bash
23
navegador ingest ./my-repo
24
```
25
26
On first run this builds the graph from scratch. Re-run anytime to pick up changes. Use `--incremental` to skip files that haven't changed (based on content hashing — much faster on large repos):
27
28
```bash
29
navegador ingest ./my-repo --incremental
30
```
31
32
Use `--watch` to keep the graph in sync as files change:
33
34
```bash
35
navegador ingest ./my-repo --watch
36
```
37
38
Use `--clear` to wipe and rebuild from scratch:
39
40
```bash
41
navegador ingest ./my-repo --clear
42
```
43
44
Use `--json` to get a machine-readable summary of what was indexed:
45
46
```bash
47
navegador ingest ./my-repo --json
48
```
49
50
Navegador walks the tree, parses source files in 13 languages with tree-sitter, and writes nodes and edges for: files, modules, classes, functions, methods, imports, decorators, and call relationships. Framework enrichers automatically detect and annotate Django models, FastAPI routes, React components, Rails controllers, Spring Boot beans, and more.
51
52
---
53
54
## Step 3: Query the graph
55
56
**Explain anything by name** — works for functions, classes, files, concepts, rules, and decisions:
After bootstrap, every file the agent edits triggers a re-ingest so the graph stays in sync. See [Agent Hooks](../guide/agent-hooks.md) for manual setup and the `NAVEGADOR.md` template.
153
154
---
155
156
## Step 6 (optional): SDK quick start
157
158
All CLI functionality is available through the Python SDK:
159
160
```python
161
from navegador import Navegador
162
163
nav = Navegador(".navegador/navegador.db")
164
165
# ingest (incremental by default in SDK)
166
nav.ingest("./my-repo", incremental=True)
167
168
# query
169
bundle = nav.explain("AuthService")
170
print(bundle.to_markdown())
171
172
# analysis
173
impact = nav.impact("validate_token")
174
churn = nav.churn(days=30)
175
cycles = nav.cycles()
176
```
177
178
The `Navegador` class wraps `GraphStore`, `ContextLoader`, all ingesters, and the analysis commands into one interface.
179
180
---
181
182
## Step 7 (optional): Code analysis
183
184
Once the graph is populated, use the analysis commands to understand your codebase: