Navegador

navegador / docs / getting-started / quickstart.md
Source Blame History 207 lines
ce0374a… lmata 1 # Quick Start
ce0374a… lmata 2
ce0374a… lmata 3 This guide walks from a fresh install to a fully wired agent integration in five steps.
ce0374a… lmata 4
ce0374a… lmata 5 ---
ce0374a… lmata 6
ce0374a… lmata 7 ## Step 1: Install
ce0374a… lmata 8
ce0374a… lmata 9 ```bash
ce0374a… lmata 10 pip install navegador
ce0374a… lmata 11 navegador --version
ce0374a… lmata 12 ```
ce0374a… lmata 13
89816aa… lmata 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.
ce0374a… lmata 15
ce0374a… lmata 16 ---
ce0374a… lmata 17
ce0374a… lmata 18 ## Step 2: Ingest a repo
ce0374a… lmata 19
ce0374a… lmata 20 Point navegador at any local source tree:
ce0374a… lmata 21
ce0374a… lmata 22 ```bash
ce0374a… lmata 23 navegador ingest ./my-repo
ce0374a… lmata 24 ```
ce0374a… lmata 25
89816aa… lmata 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):
89816aa… lmata 27
89816aa… lmata 28 ```bash
89816aa… lmata 29 navegador ingest ./my-repo --incremental
89816aa… lmata 30 ```
89816aa… lmata 31
89816aa… lmata 32 Use `--watch` to keep the graph in sync as files change:
89816aa… lmata 33
89816aa… lmata 34 ```bash
89816aa… lmata 35 navegador ingest ./my-repo --watch
89816aa… lmata 36 ```
89816aa… lmata 37
89816aa… lmata 38 Use `--clear` to wipe and rebuild from scratch:
ce0374a… lmata 39
ce0374a… lmata 40 ```bash
ce0374a… lmata 41 navegador ingest ./my-repo --clear
ce0374a… lmata 42 ```
ce0374a… lmata 43
ce0374a… lmata 44 Use `--json` to get a machine-readable summary of what was indexed:
ce0374a… lmata 45
ce0374a… lmata 46 ```bash
ce0374a… lmata 47 navegador ingest ./my-repo --json
ce0374a… lmata 48 ```
ce0374a… lmata 49
89816aa… lmata 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.
ce0374a… lmata 51
ce0374a… lmata 52 ---
ce0374a… lmata 53
ce0374a… lmata 54 ## Step 3: Query the graph
ce0374a… lmata 55
ce0374a… lmata 56 **Explain anything by name** — works for functions, classes, files, concepts, rules, and decisions:
ce0374a… lmata 57
ce0374a… lmata 58 ```bash
ce0374a… lmata 59 navegador explain AuthService
ce0374a… lmata 60 navegador explain validate_token
ce0374a… lmata 61 navegador explain src/payments/processor.py
ce0374a… lmata 62 ```
ce0374a… lmata 63
ce0374a… lmata 64 **Search across code and knowledge together:**
ce0374a… lmata 65
ce0374a… lmata 66 ```bash
ce0374a… lmata 67 navegador search "rate limit" --all
ce0374a… lmata 68 navegador search "authentication" --docs --limit 10
ce0374a… lmata 69 ```
ce0374a… lmata 70
ce0374a… lmata 71 **Inspect a function** (callers, callees, decorators, source):
ce0374a… lmata 72
ce0374a… lmata 73 ```bash
ce0374a… lmata 74 navegador function validate_token
ce0374a… lmata 75 navegador function validate_token --depth 2 --format json
ce0374a… lmata 76 ```
ce0374a… lmata 77
ce0374a… lmata 78 **Inspect a class** (hierarchy, methods, references):
ce0374a… lmata 79
ce0374a… lmata 80 ```bash
ce0374a… lmata 81 navegador class PaymentProcessor
ce0374a… lmata 82 navegador class PaymentProcessor --format json
ce0374a… lmata 83 ```
ce0374a… lmata 84
ce0374a… lmata 85 ---
ce0374a… lmata 86
ce0374a… lmata 87 ## Step 4: Add business knowledge
ce0374a… lmata 88
ce0374a… lmata 89 Code alone doesn't capture *why*. Add concepts, rules, and decisions and link them to code.
ce0374a… lmata 90
ce0374a… lmata 91 **Add a concept:**
ce0374a… lmata 92
ce0374a… lmata 93 ```bash
ce0374a… lmata 94 navegador add concept "Idempotency" \
ce0374a… lmata 95 --desc "Operations that can be retried safely without side effects" \
ce0374a… lmata 96 --domain Payments
ce0374a… lmata 97 ```
ce0374a… lmata 98
ce0374a… lmata 99 **Add a rule:**
ce0374a… lmata 100
ce0374a… lmata 101 ```bash
ce0374a… lmata 102 navegador add rule "PaymentsMustBeIdempotent" \
ce0374a… lmata 103 --desc "All payment endpoints must handle duplicate submissions" \
ce0374a… lmata 104 --domain Payments \
ce0374a… lmata 105 --severity critical \
ce0374a… lmata 106 --rationale "Card networks retry on timeout; double-charging causes chargebacks"
ce0374a… lmata 107 ```
ce0374a… lmata 108
ce0374a… lmata 109 **Annotate code with a concept or rule:**
ce0374a… lmata 110
ce0374a… lmata 111 ```bash
ce0374a… lmata 112 navegador annotate process_payment \
ce0374a… lmata 113 --type Function \
ce0374a… lmata 114 --concept Idempotency \
ce0374a… lmata 115 --rule PaymentsMustBeIdempotent
ce0374a… lmata 116 ```
ce0374a… lmata 117
ce0374a… lmata 118 **Add a decision:**
ce0374a… lmata 119
ce0374a… lmata 120 ```bash
ce0374a… lmata 121 navegador add decision "UseStripeForPayments" \
ce0374a… lmata 122 --desc "Stripe is the primary payment processor" \
ce0374a… lmata 123 --domain Payments \
ce0374a… lmata 124 --rationale "Best fraud tooling for SaaS" \
ce0374a… lmata 125 --alternatives "Braintree, Adyen" \
ce0374a… lmata 126 --date 2025-01-15 \
ce0374a… lmata 127 --status accepted
ce0374a… lmata 128 ```
ce0374a… lmata 129
ce0374a… lmata 130 Now `navegador explain process_payment` returns code structure *and* the rules that govern it.
ce0374a… lmata 131
ce0374a… lmata 132 ---
ce0374a… lmata 133
ce0374a… lmata 134 ## Step 5: Wire an agent hook
ce0374a… lmata 135
ce0374a… lmata 136 Use the bootstrap script to ingest your repo and install the hook for your AI coding assistant in one command:
ce0374a… lmata 137
ce0374a… lmata 138 ```bash
ce0374a… lmata 139 ./bootstrap.sh --repo owner/repo --wiki --agent claude
ce0374a… lmata 140 ```
ce0374a… lmata 141
ce0374a… lmata 142 Options:
ce0374a… lmata 143
ce0374a… lmata 144 | Flag | Effect |
ce0374a… lmata 145 |---|---|
ce0374a… lmata 146 | `--repo owner/repo` | GitHub repo to clone + ingest |
ce0374a… lmata 147 | `--wiki` | Also ingest the GitHub wiki |
ce0374a… lmata 148 | `--agent claude` | Install `.claude/hooks/claude-hook.py` |
ce0374a… lmata 149 | `--agent gemini` | Install `.gemini/hooks/gemini-hook.py` |
ce0374a… lmata 150 | `--agent openai` | Install `openai-hook.py` + `openai-tools.json` |
ce0374a… lmata 151
ce0374a… lmata 152 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.
89816aa… lmata 153
89816aa… lmata 154 ---
89816aa… lmata 155
89816aa… lmata 156 ## Step 6 (optional): SDK quick start
89816aa… lmata 157
89816aa… lmata 158 All CLI functionality is available through the Python SDK:
89816aa… lmata 159
89816aa… lmata 160 ```python
89816aa… lmata 161 from navegador import Navegador
89816aa… lmata 162
89816aa… lmata 163 nav = Navegador(".navegador/navegador.db")
89816aa… lmata 164
89816aa… lmata 165 # ingest (incremental by default in SDK)
89816aa… lmata 166 nav.ingest("./my-repo", incremental=True)
89816aa… lmata 167
89816aa… lmata 168 # query
89816aa… lmata 169 bundle = nav.explain("AuthService")
89816aa… lmata 170 print(bundle.to_markdown())
89816aa… lmata 171
89816aa… lmata 172 # analysis
89816aa… lmata 173 impact = nav.impact("validate_token")
89816aa… lmata 174 churn = nav.churn(days=30)
89816aa… lmata 175 cycles = nav.cycles()
89816aa… lmata 176 ```
89816aa… lmata 177
89816aa… lmata 178 The `Navegador` class wraps `GraphStore`, `ContextLoader`, all ingesters, and the analysis commands into one interface.
89816aa… lmata 179
89816aa… lmata 180 ---
89816aa… lmata 181
89816aa… lmata 182 ## Step 7 (optional): Code analysis
89816aa… lmata 183
89816aa… lmata 184 Once the graph is populated, use the analysis commands to understand your codebase:
89816aa… lmata 185
89816aa… lmata 186 ```bash
89816aa… lmata 187 # impact of changing a function
89816aa… lmata 188 navegador impact validate_token
89816aa… lmata 189
89816aa… lmata 190 # trace execution flow
89816aa… lmata 191 navegador trace process_payment --depth 3
89816aa… lmata 192
89816aa… lmata 193 # find dead code
89816aa… lmata 194 navegador deadcode
89816aa… lmata 195
89816aa… lmata 196 # detect dependency cycles
89816aa… lmata 197 navegador cycles
89816aa… lmata 198
89816aa… lmata 199 # map tests to source files
89816aa… lmata 200 navegador testmap
89816aa… lmata 201
89816aa… lmata 202 # code churn (files that change most)
89816aa… lmata 203 navegador churn --days 30
89816aa… lmata 204
89816aa… lmata 205 # diff — what changed between two refs
89816aa… lmata 206 navegador diff HEAD~1 HEAD
89816aa… lmata 207 ```

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button