|
5e4b8e4…
|
anonymous
|
1 |
# Navegador — Claude Context |
|
5e4b8e4…
|
anonymous
|
2 |
|
|
5e4b8e4…
|
anonymous
|
3 |
## What it is |
|
5e4b8e4…
|
anonymous
|
4 |
|
|
5e4b8e4…
|
anonymous
|
5 |
AST + knowledge graph context engine for AI coding agents. Parses codebases into a FalkorDB property graph. Agents query via MCP or Python API. |
|
5e4b8e4…
|
anonymous
|
6 |
|
|
5e4b8e4…
|
anonymous
|
7 |
## Stack |
|
5e4b8e4…
|
anonymous
|
8 |
|
|
4966011…
|
lmata
|
9 |
- **Python 3.12+**, standalone (no Django dependency) |
|
4966011…
|
lmata
|
10 |
- **tree-sitter** for multi-language AST parsing (13 languages) |
|
5e4b8e4…
|
anonymous
|
11 |
- **FalkorDB** graph DB with **falkordblite** (SQLite via redislite) for local use |
|
4966011…
|
lmata
|
12 |
- **MCP** (`mcp` Python SDK) for AI agent integration (11 tools) |
|
5e4b8e4…
|
anonymous
|
13 |
- **Click + Rich** for CLI |
|
5e4b8e4…
|
anonymous
|
14 |
- **Pydantic** for data models |
|
5e4b8e4…
|
anonymous
|
15 |
- **Ruff** for linting/formatting |
|
5e4b8e4…
|
anonymous
|
16 |
|
|
5e4b8e4…
|
anonymous
|
17 |
## Package layout |
|
5e4b8e4…
|
anonymous
|
18 |
|
|
5e4b8e4…
|
anonymous
|
19 |
``` |
|
5e4b8e4…
|
anonymous
|
20 |
navegador/ |
|
4966011…
|
lmata
|
21 |
cli/ — Click commands (50+ subcommands) |
|
4966011…
|
lmata
|
22 |
graph/ — GraphStore + schema + queries + migrations + export |
|
4966011…
|
lmata
|
23 |
ingestion/ — RepoIngester + 13 language parsers + optimization |
|
4966011…
|
lmata
|
24 |
context/ — ContextLoader + ContextBundle (JSON/markdown) |
|
4966011…
|
lmata
|
25 |
mcp/ — MCP server with 11 tools + security hardening |
|
4966011…
|
lmata
|
26 |
enrichment/ — FrameworkEnricher base + 8 framework enrichers |
|
4966011…
|
lmata
|
27 |
analysis/ — impact, flow tracing, dead code, cycles, test mapping |
|
4966011…
|
lmata
|
28 |
intelligence/ — semantic search, community detection, NLP, doc generation |
|
4966011…
|
lmata
|
29 |
cluster/ — Redis pub/sub, task queue, locking, sessions, messaging |
|
4966011…
|
lmata
|
30 |
sdk.py — Python SDK (Navegador class) |
|
4966011…
|
lmata
|
31 |
llm.py — LLM provider abstraction (Anthropic, OpenAI, Ollama) |
|
4966011…
|
lmata
|
32 |
vcs.py — VCS abstraction (Git, Fossil) |
|
4966011…
|
lmata
|
33 |
diff.py — Git diff → graph impact mapping |
|
4966011…
|
lmata
|
34 |
churn.py — Behavioural coupling from git history |
|
4966011…
|
lmata
|
35 |
monorepo.py — Workspace detection + ingestion |
|
4966011…
|
lmata
|
36 |
security.py — Sensitive content detection + redaction |
|
4966011…
|
lmata
|
37 |
explorer/ — HTTP server + browser-based graph visualization |
|
5e4b8e4…
|
anonymous
|
38 |
``` |
|
5e4b8e4…
|
anonymous
|
39 |
|
|
5e4b8e4…
|
anonymous
|
40 |
## FalkorDB connection |
|
5e4b8e4…
|
anonymous
|
41 |
|
|
5e4b8e4…
|
anonymous
|
42 |
```python |
|
5e4b8e4…
|
anonymous
|
43 |
# SQLite (local, zero-infra) — uses falkordblite |
|
5e4b8e4…
|
anonymous
|
44 |
from redislite import FalkorDB # falkordblite provides this |
|
5e4b8e4…
|
anonymous
|
45 |
db = FalkorDB("path/to/graph.db") |
|
5e4b8e4…
|
anonymous
|
46 |
graph = db.select_graph("navegador") |
|
5e4b8e4…
|
anonymous
|
47 |
|
|
5e4b8e4…
|
anonymous
|
48 |
# Redis (production) |
|
5e4b8e4…
|
anonymous
|
49 |
import falkordb |
|
5e4b8e4…
|
anonymous
|
50 |
client = falkordb.FalkorDB.from_url("redis://localhost:6379") |
|
5e4b8e4…
|
anonymous
|
51 |
``` |
|
5e4b8e4…
|
anonymous
|
52 |
|
|
5e4b8e4…
|
anonymous
|
53 |
## Adding a new language parser |
|
5e4b8e4…
|
anonymous
|
54 |
|
|
5e4b8e4…
|
anonymous
|
55 |
1. Create `navegador/ingestion/<lang>.py` subclassing `LanguageParser` |
|
5e4b8e4…
|
anonymous
|
56 |
2. Implement `parse_file(path, repo_root, store) -> dict[str, int]` |
|
5e4b8e4…
|
anonymous
|
57 |
3. Add the extension + language key to `LANGUAGE_MAP` in `parser.py` |
|
5e4b8e4…
|
anonymous
|
58 |
4. Register in `RepoIngester._get_parser()` |
|
4966011…
|
lmata
|
59 |
|
|
4966011…
|
lmata
|
60 |
## Adding a new framework enricher |
|
4966011…
|
lmata
|
61 |
|
|
4966011…
|
lmata
|
62 |
1. Create `navegador/enrichment/<framework>.py` subclassing `FrameworkEnricher` |
|
4966011…
|
lmata
|
63 |
2. Implement `framework_name`, `detection_patterns`, `enrich()` |
|
4966011…
|
lmata
|
64 |
3. The CLI auto-discovers enrichers via `pkgutil` — no registration needed |
|
5e4b8e4…
|
anonymous
|
65 |
|
|
5e4b8e4…
|
anonymous
|
66 |
## Adding a new MCP tool |
|
5e4b8e4…
|
anonymous
|
67 |
|
|
5e4b8e4…
|
anonymous
|
68 |
1. Add a `Tool(...)` entry in `list_tools()` in `mcp/server.py` |
|
5e4b8e4…
|
anonymous
|
69 |
2. Add a handler branch in `call_tool()` |
|
5e4b8e4…
|
anonymous
|
70 |
|
|
5e4b8e4…
|
anonymous
|
71 |
## Running tests |
|
5e4b8e4…
|
anonymous
|
72 |
|
|
5e4b8e4…
|
anonymous
|
73 |
```bash |
|
5e4b8e4…
|
anonymous
|
74 |
pip install -e ".[dev]" |
|
5e4b8e4…
|
anonymous
|
75 |
pytest tests/ -v |
|
5e4b8e4…
|
anonymous
|
76 |
``` |
|
5e4b8e4…
|
anonymous
|
77 |
|
|
5e4b8e4…
|
anonymous
|
78 |
## Linting |
|
5e4b8e4…
|
anonymous
|
79 |
|
|
5e4b8e4…
|
anonymous
|
80 |
```bash |
|
5e4b8e4…
|
anonymous
|
81 |
ruff check navegador/ |
|
5e4b8e4…
|
anonymous
|
82 |
ruff format navegador/ |
|
5e4b8e4…
|
anonymous
|
83 |
``` |
|
5e4b8e4…
|
anonymous
|
84 |
|
|
5e4b8e4…
|
anonymous
|
85 |
## Docs |
|
5e4b8e4…
|
anonymous
|
86 |
|
|
5e4b8e4…
|
anonymous
|
87 |
```bash |
|
5e4b8e4…
|
anonymous
|
88 |
pip install -e ".[docs]" |
|
5e4b8e4…
|
anonymous
|
89 |
mkdocs serve # local preview at http://localhost:8000 |
|
5e4b8e4…
|
anonymous
|
90 |
mkdocs gh-deploy --force # deploy to navegador.dev |
|
5e4b8e4…
|
anonymous
|
91 |
``` |