Navegador

navegador / README.md
Source Blame History 282 lines
5e4b8e4… anonymous 1 # Navegador
5e4b8e4… anonymous 2
436ffa9… lmata 3 **Your codebase + everything your team knows about it — in one queryable graph.**
5e4b8e4… anonymous 4
436ffa9… lmata 5 Navegador parses your source code into a property graph and layers your team's knowledge on top: decisions, concepts, rules, people, wiki pages, and meeting outputs. AI coding agents get structured, precise context instead of raw file dumps.
5e4b8e4… anonymous 6
5e4b8e4… anonymous 7 > *navegador* — Spanish for *navigator / sailor*
5e4b8e4… anonymous 8
5e4b8e4… anonymous 9 [![CI](https://github.com/ConflictHQ/navegador/actions/workflows/ci.yml/badge.svg)](https://github.com/ConflictHQ/navegador/actions/workflows/ci.yml)
5e4b8e4… anonymous 10 [![PyPI](https://img.shields.io/pypi/v/navegador)](https://pypi.org/project/navegador/)
436ffa9… lmata 11 [![Python](https://img.shields.io/pypi/pyversions/navegador)](https://pypi.org/project/navegador/)
5e4b8e4… anonymous 12 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
5e4b8e4… anonymous 13 [![Docs](https://img.shields.io/badge/docs-navegador.dev-blue)](https://navegador.dev)
5e4b8e4… anonymous 14
5e4b8e4… anonymous 15 ---
5e4b8e4… anonymous 16
436ffa9… lmata 17 ## Two layers, one graph
5e4b8e4… anonymous 18
436ffa9… lmata 19 ```
436ffa9… lmata 20 ┌─────────────────────────────────────────────────────────────────┐
436ffa9… lmata 21 │ KNOWLEDGE LAYER │
aee7203… lmata 22 │ Concepts · Rules · Decisions · WikiPages · People · Domains │
436ffa9… lmata 23 │ │
aee7203… lmata 24 │ ↕ GOVERNS / IMPLEMENTS / DOCUMENTS / ANNOTATES │
436ffa9… lmata 25 │ │
436ffa9… lmata 26 │ CODE LAYER │
aee7203… lmata 27 │ Repository · File · Module · Class · Function · Method │
aee7203… lmata 28 │ Variable · Import · Decorator · (call graphs, hierarchies) │
436ffa9… lmata 29 └─────────────────────────────────────────────────────────────────┘
436ffa9… lmata 30 stored in FalkorDB (SQLite local · Redis prod)
436ffa9… lmata 31 ```
436ffa9… lmata 32
436ffa9… lmata 33 The **code layer** is built automatically by ingesting source trees. The **knowledge layer** is populated by your team — manually, via wiki ingestion, or from [PlanOpticon](https://github.com/ConflictHQ/PlanOpticon) meeting analysis output.
5e4b8e4… anonymous 34
5e4b8e4… anonymous 35 ---
5e4b8e4… anonymous 36
5e4b8e4… anonymous 37 ## Quick start
5e4b8e4… anonymous 38
5e4b8e4… anonymous 39 ```bash
5e4b8e4… anonymous 40 pip install navegador
5e4b8e4… anonymous 41
5e4b8e4… anonymous 42 # Ingest your repo
5e4b8e4… anonymous 43 navegador ingest ./myrepo
5e4b8e4… anonymous 44
5e4b8e4… anonymous 45 # Load context for a file
5e4b8e4… anonymous 46 navegador context src/auth.py
5e4b8e4… anonymous 47
436ffa9… lmata 48 # Search across code + knowledge
436ffa9… lmata 49 navegador search "rate limit" --all
436ffa9… lmata 50
436ffa9… lmata 51 # Explain a symbol
436ffa9… lmata 52 navegador explain AuthService
5e4b8e4… anonymous 53
5e4b8e4… anonymous 54 # Check graph stats
5e4b8e4… anonymous 55 navegador stats
5e4b8e4… anonymous 56 ```
5e4b8e4… anonymous 57
5e4b8e4… anonymous 58 ---
5e4b8e4… anonymous 59
5e4b8e4… anonymous 60 ## MCP integration
5e4b8e4… anonymous 61
436ffa9… lmata 62 Add to your Claude / Cursor / Gemini MCP config:
5e4b8e4… anonymous 63
5e4b8e4… anonymous 64 ```json
5e4b8e4… anonymous 65 {
5e4b8e4… anonymous 66 "mcpServers": {
5e4b8e4… anonymous 67 "navegador": {
5e4b8e4… anonymous 68 "command": "navegador",
5e4b8e4… anonymous 69 "args": ["mcp", "--db", ".navegador/graph.db"]
5e4b8e4… anonymous 70 }
5e4b8e4… anonymous 71 }
5e4b8e4… anonymous 72 }
5e4b8e4… anonymous 73 ```
5e4b8e4… anonymous 74
5e4b8e4… anonymous 75 Available MCP tools:
5e4b8e4… anonymous 76
5e4b8e4… anonymous 77 | Tool | Description |
5e4b8e4… anonymous 78 |------|-------------|
5e4b8e4… anonymous 79 | `ingest_repo` | Parse and load a repo into the graph |
5e4b8e4… anonymous 80 | `load_file_context` | All symbols in a file + their relationships |
5e4b8e4… anonymous 81 | `load_function_context` | What a function calls and what calls it |
5e4b8e4… anonymous 82 | `load_class_context` | Class methods, inheritance, subclasses |
5e4b8e4… anonymous 83 | `search_symbols` | Fuzzy search for functions/classes by name |
4966011… lmata 84 | `query_graph` | Raw Cypher passthrough (with security hardening) |
5e4b8e4… anonymous 85 | `graph_stats` | Node and edge counts |
4966011… lmata 86 | `get_rationale` | Decision rationale, alternatives, and status |
4966011… lmata 87 | `find_owners` | People assigned to any node |
4966011… lmata 88 | `search_knowledge` | Search concepts, rules, decisions, wiki |
4966011… lmata 89 | `blast_radius` | Impact analysis — what's affected by a change |
436ffa9… lmata 90
436ffa9… lmata 91 ---
436ffa9… lmata 92
436ffa9… lmata 93 ## Knowledge layer
436ffa9… lmata 94
436ffa9… lmata 95 Beyond code structure, navegador stores what your team knows:
436ffa9… lmata 96
436ffa9… lmata 97 ```bash
436ffa9… lmata 98 # Record an architectural decision
436ffa9… lmata 99 navegador add decision "Use FalkorDB for graph storage" \
436ffa9… lmata 100 --rationale "Cypher queries, SQLite-backed zero-infra mode"
436ffa9… lmata 101
436ffa9… lmata 102 # Define a business concept and link it to code
436ffa9… lmata 103 navegador add concept PaymentProcessing
436ffa9… lmata 104 navegador annotate PaymentProcessing --function process_charge
436ffa9… lmata 105
436ffa9… lmata 106 # Add a rule
436ffa9… lmata 107 navegador add rule "All writes must go through the service layer"
436ffa9… lmata 108
436ffa9… lmata 109 # Ingest your GitHub wiki
436ffa9… lmata 110 navegador wiki ingest --repo myorg/myrepo
436ffa9… lmata 111
436ffa9… lmata 112 # Import PlanOpticon meeting analysis
436ffa9… lmata 113 navegador planopticon ingest ./meeting-output/
436ffa9… lmata 114 ```
5e4b8e4… anonymous 115
5e4b8e4… anonymous 116 ---
5e4b8e4… anonymous 117
5e4b8e4… anonymous 118 ## Graph schema
5e4b8e4… anonymous 119
436ffa9… lmata 120 **Code nodes:** `Repository` · `File` · `Module` · `Class` · `Function` · `Method` · `Variable` · `Import` · `Decorator`
436ffa9… lmata 121
436ffa9… lmata 122 **Knowledge nodes:** `Concept` · `Rule` · `Decision` · `Person` · `Domain` · `WikiPage`
5e4b8e4… anonymous 123
436ffa9… lmata 124 **Edges:** `CONTAINS` · `DEFINES` · `IMPORTS` · `CALLS` · `INHERITS` · `REFERENCES` · `DEPENDS_ON` · `GOVERNS` · `IMPLEMENTS` · `DOCUMENTS` · `ANNOTATES`
5e4b8e4… anonymous 125
5e4b8e4… anonymous 126 ---
5e4b8e4… anonymous 127
5e4b8e4… anonymous 128 ## Storage
5e4b8e4… anonymous 129
5e4b8e4… anonymous 130 | Mode | Backend | When to use |
5e4b8e4… anonymous 131 |------|---------|-------------|
5e4b8e4… anonymous 132 | Default | `falkordblite` (SQLite) | Local dev, zero infrastructure |
436ffa9… lmata 133 | Production | Redis + FalkorDB module | Shared deployments, agent swarms |
5e4b8e4… anonymous 134
5e4b8e4… anonymous 135 ```python
5e4b8e4… anonymous 136 from navegador.graph import GraphStore
5e4b8e4… anonymous 137
436ffa9… lmata 138 store = GraphStore.sqlite(".navegador/graph.db") # default
436ffa9… lmata 139 store = GraphStore.redis("redis://localhost:6379") # production
5e4b8e4… anonymous 140 ```
5e4b8e4… anonymous 141
5e4b8e4… anonymous 142 ---
5e4b8e4… anonymous 143
5e4b8e4… anonymous 144 ## Language support
5e4b8e4… anonymous 145
5e4b8e4… anonymous 146 | Language | Status |
5e4b8e4… anonymous 147 |----------|--------|
5e4b8e4… anonymous 148 | Python | ✅ |
5e4b8e4… anonymous 149 | TypeScript / JavaScript | ✅ |
758c6b7… lmata 150 | Go | ✅ |
758c6b7… lmata 151 | Rust | ✅ |
758c6b7… lmata 152 | Java | ✅ |
4966011… lmata 153 | Kotlin | ✅ |
4966011… lmata 154 | C# | ✅ |
4966011… lmata 155 | PHP | ✅ |
4966011… lmata 156 | Ruby | ✅ |
4966011… lmata 157 | Swift | ✅ |
4966011… lmata 158 | C / C++ | ✅ |
4966011… lmata 159
4966011… lmata 160 ---
4966011… lmata 161
4966011… lmata 162 ## Framework enrichment
4966011… lmata 163
4966011… lmata 164 After ingesting code, navegador can promote generic AST nodes to framework-specific semantic types:
4966011… lmata 165
4966011… lmata 166 ```bash
4966011… lmata 167 navegador enrich # auto-detect frameworks
4966011… lmata 168 navegador enrich --framework django # target a specific framework
4966011… lmata 169 ```
4966011… lmata 170
4966011… lmata 171 Supported frameworks: **Django**, **FastAPI**, **React / Next.js**, **Express.js**, **React Native**, **Rails**, **Spring Boot**, **Laravel**
4966011… lmata 172
4966011… lmata 173 ---
4966011… lmata 174
4966011… lmata 175 ## Structural analysis
4966011… lmata 176
4966011… lmata 177 ```bash
4966011… lmata 178 navegador impact AuthService --depth 3 # blast radius
4966011… lmata 179 navegador trace handle_request # execution flow from entry point
4966011… lmata 180 navegador deadcode # unreachable functions/classes
4966011… lmata 181 navegador cycles # circular dependencies
4966011… lmata 182 navegador testmap # link tests to production code
4966011… lmata 183 navegador diff # map uncommitted changes to graph
4966011… lmata 184 navegador churn . # behavioural coupling from git history
4966011… lmata 185 ```
4966011… lmata 186
4966011… lmata 187 ---
4966011… lmata 188
4966011… lmata 189 ## Intelligence layer
4966011… lmata 190
4966011… lmata 191 ```bash
4966011… lmata 192 navegador semantic-search "authentication flow" # embedding-based search
4966011… lmata 193 navegador communities # detect code communities
4966011… lmata 194 navegador ask "what calls the payment service?" # natural language queries
4966011… lmata 195 navegador docs src/auth.py # generate documentation
4966011… lmata 196 ```
4966011… lmata 197
4966011… lmata 198 Requires an LLM provider: `pip install navegador[llm]`
4966011… lmata 199
4966011… lmata 200 ---
4966011… lmata 201
4966011… lmata 202 ## Python SDK
4966011… lmata 203
4966011… lmata 204 ```python
4966011… lmata 205 from navegador import Navegador
4966011… lmata 206
4966011… lmata 207 nav = Navegador.sqlite(".navegador/graph.db")
4966011… lmata 208 nav.ingest("./myrepo")
4966011… lmata 209 nav.add_concept("Payment", description="Payment processing", domain="billing")
4966011… lmata 210
4966011… lmata 211 results = nav.search("auth")
4966011… lmata 212 bundle = nav.explain("AuthService")
4966011… lmata 213 owners = nav.find_owners("AuthService")
4966011… lmata 214 ```
4966011… lmata 215
4966011… lmata 216 ---
4966011… lmata 217
4966011… lmata 218 ## Cluster mode (agent swarms)
4966011… lmata 219
4966011… lmata 220 For multi-agent setups sharing a Redis-backed graph:
4966011… lmata 221
4966011… lmata 222 ```bash
4966011… lmata 223 navegador init --redis redis://host:6379 --cluster
4966011… lmata 224 ```
4966011… lmata 225
4966011… lmata 226 Features: shared graph with local snapshots, pub/sub notifications, task queues, distributed locking, session namespacing, checkpoints, agent messaging, observability dashboard.
4966011… lmata 227
4966011… lmata 228 ---
4966011… lmata 229
4966011… lmata 230 ## Additional integrations
4966011… lmata 231
4966011… lmata 232 ```bash
4966011… lmata 233 navegador codeowners ./myrepo # parse CODEOWNERS → ownership graph
4966011… lmata 234 navegador adr ingest docs/decisions/ # Architecture Decision Records
4966011… lmata 235 navegador api ingest openapi.yaml # OpenAPI / GraphQL schemas
4966011… lmata 236 navegador deps ingest package.json # external dependency tracking
4966011… lmata 237 navegador pm ingest --github org/repo # GitHub issues → knowledge graph
4966011… lmata 238 navegador editor setup claude-code # generate MCP config for editors
4966011… lmata 239 navegador explore # browser-based graph visualization
4966011… lmata 240 ```
436ffa9… lmata 241
436ffa9… lmata 242 ---
436ffa9… lmata 243
436ffa9… lmata 244 ## Installation
436ffa9… lmata 245
436ffa9… lmata 246 ### PyPI
436ffa9… lmata 247
436ffa9… lmata 248 ```bash
436ffa9… lmata 249 pip install navegador
436ffa9… lmata 250 ```
436ffa9… lmata 251
436ffa9… lmata 252 ### Standalone binaries
436ffa9… lmata 253
436ffa9… lmata 254 No Python required — download prebuilt binaries from [GitHub Releases](https://github.com/ConflictHQ/navegador/releases):
436ffa9… lmata 255
436ffa9… lmata 256 | Platform | Binary |
436ffa9… lmata 257 |----------|--------|
436ffa9… lmata 258 | macOS (Apple Silicon) | `navegador-macos-arm64` |
436ffa9… lmata 259 | macOS (Intel) | `navegador-macos-x86_64` |
436ffa9… lmata 260 | Linux | `navegador-linux-x86_64` |
436ffa9… lmata 261 | Windows | `navegador-windows-x86_64.exe` |
436ffa9… lmata 262
436ffa9… lmata 263 ### From source
436ffa9… lmata 264
436ffa9… lmata 265 ```bash
436ffa9… lmata 266 git clone https://github.com/ConflictHQ/navegador.git
436ffa9… lmata 267 cd navegador
436ffa9… lmata 268 pip install -e ".[dev]"
436ffa9… lmata 269 pytest
436ffa9… lmata 270 ```
436ffa9… lmata 271
436ffa9… lmata 272 ---
436ffa9… lmata 273
436ffa9… lmata 274 ## Contributing
436ffa9… lmata 275
436ffa9… lmata 276 See [CONTRIBUTING.md](.github/CONTRIBUTING.md). Bug reports and feature requests welcome via [GitHub Issues](https://github.com/ConflictHQ/navegador/issues).
5e4b8e4… anonymous 277
5e4b8e4… anonymous 278 ---
5e4b8e4… anonymous 279
5e4b8e4… anonymous 280 ## License
5e4b8e4… anonymous 281
5ef47aa… lmata 282 MIT — [CONFLICT](https://weareconflict.com)

Keyboard Shortcuts

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