Navegador

navegador / README.md

Source Rendered

Blame History Raw 283 lines

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

Navegador

Keyboard Shortcuts