Navegador
docs: open source prep — README, CODE_OF_CONDUCT, issue templates - README rewritten to lead with knowledge layer, add binary install section, full graph schema, and contributing link - CODE_OF_CONDUCT.md added - Bug report and feature request issue templates added
Commit
436ffa93a5b2b1a415b7ac6730e0dcae6e53bcb8c68b60ff5956d37f0cda00df
Parent
d501fb2fd9afa54…
4 files changed
+51
+35
+27
+93
-17
| --- a/.github/ISSUE_TEMPLATE/bug_report.yml | ||
| +++ b/.github/ISSUE_TEMPLATE/bug_report.yml | ||
| @@ -0,0 +1,51 @@ | ||
| 1 | +name: Bug report | |
| 2 | +description: Something isn't working | |
| 3 | +labels: ["bug"] | |
| 4 | +body: | |
| 5 | + - type: markdown | |
| 6 | + attributes: | |
| 7 | + value: Thanks for taking the time to report a bug. | |
| 8 | + | |
| 9 | + - type: textarea | |
| 10 | + id: description | |
| 11 | + attributes: | |
| 12 | + label: What happened? | |
| 13 | + description: A clear description of the bug. | |
| 14 | + validations: | |
| 15 | + required: true | |
| 16 | + | |
| 17 | + - type: textarea | |
| 18 | + id: reproduction | |
| 19 | + attributes: | |
| 20 | + label: Steps to reproduce | |
| 21 | + placeholder: | | |
| 22 | + 1. Run `navegador ingest ./myrepo` | |
| 23 | + 2. Run `navegador context src/auth.py` | |
| 24 | + 3. ... | |
| 25 | + validations: | |
| 26 | + required: true | |
| 27 | + | |
| 28 | + - type: textarea | |
| 29 | + id: expected | |
| 30 | + attributes: | |
| 31 | + label: Expected behaviour | |
| 32 | + validations: | |
| 33 | + required: true | |
| 34 | + | |
| 35 | + - type: textarea | |
| 36 | + id: environment | |
| 37 | + attributes: | |
| 38 | + label: Environment | |
| 39 | + placeholder: | | |
| 40 | + - navegador version: 0.1.0 | |
| 41 | + - Python: 3.12 | |
| 42 | + - OS: macOS 15 / Ubuntu 24.04 | |
| 43 | + - Storage: SQLite / Redis | |
| 44 | + validations: | |
| 45 | + required: true | |
| 46 | + | |
| 47 | + - type: textarea | |
| 48 | + id: logs | |
| 49 | + attributes: | |
| 50 | + label: Relevant logs or output | |
| 51 | + render: shell |
| --- a/.github/ISSUE_TEMPLATE/bug_report.yml | |
| +++ b/.github/ISSUE_TEMPLATE/bug_report.yml | |
| @@ -0,0 +1,51 @@ | |
| --- a/.github/ISSUE_TEMPLATE/bug_report.yml | |
| +++ b/.github/ISSUE_TEMPLATE/bug_report.yml | |
| @@ -0,0 +1,51 @@ | |
| 1 | name: Bug report |
| 2 | description: Something isn't working |
| 3 | labels: ["bug"] |
| 4 | body: |
| 5 | - type: markdown |
| 6 | attributes: |
| 7 | value: Thanks for taking the time to report a bug. |
| 8 | |
| 9 | - type: textarea |
| 10 | id: description |
| 11 | attributes: |
| 12 | label: What happened? |
| 13 | description: A clear description of the bug. |
| 14 | validations: |
| 15 | required: true |
| 16 | |
| 17 | - type: textarea |
| 18 | id: reproduction |
| 19 | attributes: |
| 20 | label: Steps to reproduce |
| 21 | placeholder: | |
| 22 | 1. Run `navegador ingest ./myrepo` |
| 23 | 2. Run `navegador context src/auth.py` |
| 24 | 3. ... |
| 25 | validations: |
| 26 | required: true |
| 27 | |
| 28 | - type: textarea |
| 29 | id: expected |
| 30 | attributes: |
| 31 | label: Expected behaviour |
| 32 | validations: |
| 33 | required: true |
| 34 | |
| 35 | - type: textarea |
| 36 | id: environment |
| 37 | attributes: |
| 38 | label: Environment |
| 39 | placeholder: | |
| 40 | - navegador version: 0.1.0 |
| 41 | - Python: 3.12 |
| 42 | - OS: macOS 15 / Ubuntu 24.04 |
| 43 | - Storage: SQLite / Redis |
| 44 | validations: |
| 45 | required: true |
| 46 | |
| 47 | - type: textarea |
| 48 | id: logs |
| 49 | attributes: |
| 50 | label: Relevant logs or output |
| 51 | render: shell |
| --- a/.github/ISSUE_TEMPLATE/feature_request.yml | ||
| +++ b/.github/ISSUE_TEMPLATE/feature_request.yml | ||
| @@ -0,0 +1,35 @@ | ||
| 1 | +name: Feature request | |
| 2 | +description: Suggest something new | |
| 3 | +labels: ["enhancement"] | |
| 4 | +body: | |
| 5 | + - type: markdown | |
| 6 | + attributes: | |
| 7 | + value: Thanks for suggesting a feature. | |
| 8 | + | |
| 9 | + - type: textarea | |
| 10 | + id: problem | |
| 11 | + attributes: | |
| 12 | + label: What problem does this solve? | |
| 13 | + description: Describe the context and the gap you're running into. | |
| 14 | + validations: | |
| 15 | + required: true | |
| 16 | + | |
| 17 | + - type: textarea | |
| 18 | + id: solution | |
| 19 | + attributes: | |
| 20 | + label: Proposed solution | |
| 21 | + description: What would you like to see? | |
| 22 | + validations: | |
| 23 | + required: true | |
| 24 | + | |
| 25 | + - type: textarea | |
| 26 | + id: alternatives | |
| 27 | + attributes: | |
| 28 | + label: Alternatives considered | |
| 29 | + description: Any other approaches you've thought about? | |
| 30 | + | |
| 31 | + - type: textarea | |
| 32 | + id: context | |
| 33 | + attributes: | |
| 34 | + label: Additional context | |
| 35 | + description: Links, examples, prior art — anything useful. |
| --- a/.github/ISSUE_TEMPLATE/feature_request.yml | |
| +++ b/.github/ISSUE_TEMPLATE/feature_request.yml | |
| @@ -0,0 +1,35 @@ | |
| --- a/.github/ISSUE_TEMPLATE/feature_request.yml | |
| +++ b/.github/ISSUE_TEMPLATE/feature_request.yml | |
| @@ -0,0 +1,35 @@ | |
| 1 | name: Feature request |
| 2 | description: Suggest something new |
| 3 | labels: ["enhancement"] |
| 4 | body: |
| 5 | - type: markdown |
| 6 | attributes: |
| 7 | value: Thanks for suggesting a feature. |
| 8 | |
| 9 | - type: textarea |
| 10 | id: problem |
| 11 | attributes: |
| 12 | label: What problem does this solve? |
| 13 | description: Describe the context and the gap you're running into. |
| 14 | validations: |
| 15 | required: true |
| 16 | |
| 17 | - type: textarea |
| 18 | id: solution |
| 19 | attributes: |
| 20 | label: Proposed solution |
| 21 | description: What would you like to see? |
| 22 | validations: |
| 23 | required: true |
| 24 | |
| 25 | - type: textarea |
| 26 | id: alternatives |
| 27 | attributes: |
| 28 | label: Alternatives considered |
| 29 | description: Any other approaches you've thought about? |
| 30 | |
| 31 | - type: textarea |
| 32 | id: context |
| 33 | attributes: |
| 34 | label: Additional context |
| 35 | description: Links, examples, prior art — anything useful. |
+27
| --- a/CODE_OF_CONDUCT.md | ||
| +++ b/CODE_OF_CONDUCT.md | ||
| @@ -0,0 +1,27 @@ | ||
| 1 | +# Code of Conduct | |
| 2 | + | |
| 3 | +## Our pledge | |
| 4 | + | |
| 5 | +We are committed to making participation in this project a harassment-free experience for everyone, regardless of age, background, disability, ethnicity, gender identity, level of experience, nationality, personal appearance, race, religion, or sexual identity. | |
| 6 | + | |
| 7 | +## Our standards | |
| 8 | + | |
| 9 | +**Expected behaviour:** | |
| 10 | +- Be respectful and constructive in discussions | |
| 11 | +- Accept feedback gracefully and give it generously | |
| 12 | +- Focus on what is best for the project and its users | |
| 13 | +- Show empathy toward other contributors | |
| 14 | + | |
| 15 | +**Unacceptable behaviour:** | |
| 16 | +- Harassment, insults, or personal attacks | |
| 17 | +- Trolling or deliberately disruptive behaviour | |
| 18 | +- Publishing others' private information without permission | |
| 19 | +- Any conduct that would be inappropriate in a professional setting | |
| 20 | + | |
| 21 | +## Enforcement | |
| 22 | + | |
| 23 | +Instances of unacceptable behaviour may be reported to **[email protected]**. All reports will be reviewed and investigated promptly and fairly. Project maintainers have the right to remove, edit, or reject contributions that do not align with this Code of Conduct. | |
| 24 | + | |
| 25 | +## Attribution | |
| 26 | + | |
| 27 | +Adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1. |
| --- a/CODE_OF_CONDUCT.md | |
| +++ b/CODE_OF_CONDUCT.md | |
| @@ -0,0 +1,27 @@ | |
| --- a/CODE_OF_CONDUCT.md | |
| +++ b/CODE_OF_CONDUCT.md | |
| @@ -0,0 +1,27 @@ | |
| 1 | # Code of Conduct |
| 2 | |
| 3 | ## Our pledge |
| 4 | |
| 5 | We are committed to making participation in this project a harassment-free experience for everyone, regardless of age, background, disability, ethnicity, gender identity, level of experience, nationality, personal appearance, race, religion, or sexual identity. |
| 6 | |
| 7 | ## Our standards |
| 8 | |
| 9 | **Expected behaviour:** |
| 10 | - Be respectful and constructive in discussions |
| 11 | - Accept feedback gracefully and give it generously |
| 12 | - Focus on what is best for the project and its users |
| 13 | - Show empathy toward other contributors |
| 14 | |
| 15 | **Unacceptable behaviour:** |
| 16 | - Harassment, insults, or personal attacks |
| 17 | - Trolling or deliberately disruptive behaviour |
| 18 | - Publishing others' private information without permission |
| 19 | - Any conduct that would be inappropriate in a professional setting |
| 20 | |
| 21 | ## Enforcement |
| 22 | |
| 23 | Instances of unacceptable behaviour may be reported to **[email protected]**. All reports will be reviewed and investigated promptly and fairly. Project maintainers have the right to remove, edit, or reject contributions that do not align with this Code of Conduct. |
| 24 | |
| 25 | ## Attribution |
| 26 | |
| 27 | Adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1. |
+93
-17
| --- README.md | ||
| +++ README.md | ||
| @@ -1,23 +1,38 @@ | ||
| 1 | 1 | # Navegador |
| 2 | 2 | |
| 3 | -**AST + knowledge graph context engine for AI coding agents.** | |
| 3 | +**Your codebase + everything your team knows about it — in one queryable graph.** | |
| 4 | 4 | |
| 5 | -Navegador parses your codebase into a property graph and makes it queryable. AI coding agents can ask "what calls this function?", "what does this file depend on?", or "show me everything related to auth" — and get structured, precise answers instead of raw file dumps. | |
| 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 | 6 | |
| 7 | 7 | > *navegador* — Spanish for *navigator / sailor* |
| 8 | 8 | |
| 9 | 9 | [](https://github.com/ConflictHQ/navegador/actions/workflows/ci.yml) |
| 10 | 10 | [](https://pypi.org/project/navegador/) |
| 11 | +[](https://pypi.org/project/navegador/) | |
| 11 | 12 | [](LICENSE) |
| 12 | 13 | [](https://navegador.dev) |
| 13 | 14 | |
| 14 | 15 | --- |
| 15 | 16 | |
| 16 | -## Why | |
| 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 | +``` | |
| 17 | 32 | |
| 18 | -AI coding agents load context by reading raw files. They don't know what calls what, what depends on what, or which 5 functions out of 500 are actually relevant. Navegador builds a structured map — then exposes it via MCP so any agent can navigate your code with precision. | |
| 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. | |
| 19 | 34 | |
| 20 | 35 | --- |
| 21 | 36 | |
| 22 | 37 | ## Quick start |
| 23 | 38 | |
| @@ -28,22 +43,25 @@ | ||
| 28 | 43 | navegador ingest ./myrepo |
| 29 | 44 | |
| 30 | 45 | # Load context for a file |
| 31 | 46 | navegador context src/auth.py |
| 32 | 47 | |
| 33 | -# Search for a symbol | |
| 34 | -navegador search "get_user" | |
| 48 | +# Search across code + knowledge | |
| 49 | +navegador search "rate limit" --all | |
| 50 | + | |
| 51 | +# Explain a symbol | |
| 52 | +navegador explain AuthService | |
| 35 | 53 | |
| 36 | 54 | # Check graph stats |
| 37 | 55 | navegador stats |
| 38 | 56 | ``` |
| 39 | 57 | |
| 40 | 58 | --- |
| 41 | 59 | |
| 42 | 60 | ## MCP integration |
| 43 | 61 | |
| 44 | -Add to your Claude / Cursor MCP config: | |
| 62 | +Add to your Claude / Cursor / Gemini MCP config: | |
| 45 | 63 | |
| 46 | 64 | ```json |
| 47 | 65 | { |
| 48 | 66 | "mcpServers": { |
| 49 | 67 | "navegador": { |
| @@ -65,36 +83,58 @@ | ||
| 65 | 83 | | `search_symbols` | Fuzzy search for functions/classes by name | |
| 66 | 84 | | `query_graph` | Raw Cypher passthrough | |
| 67 | 85 | | `graph_stats` | Node and edge counts | |
| 68 | 86 | |
| 69 | 87 | --- |
| 88 | + | |
| 89 | +## Knowledge layer | |
| 90 | + | |
| 91 | +Beyond code structure, navegador stores what your team knows: | |
| 92 | + | |
| 93 | +```bash | |
| 94 | +# Record an architectural decision | |
| 95 | +navegador add decision "Use FalkorDB for graph storage" \ | |
| 96 | + --rationale "Cypher queries, SQLite-backed zero-infra mode" | |
| 97 | + | |
| 98 | +# Define a business concept and link it to code | |
| 99 | +navegador add concept PaymentProcessing | |
| 100 | +navegador annotate PaymentProcessing --function process_charge | |
| 101 | + | |
| 102 | +# Add a rule | |
| 103 | +navegador add rule "All writes must go through the service layer" | |
| 104 | + | |
| 105 | +# Ingest your GitHub wiki | |
| 106 | +navegador wiki ingest --repo myorg/myrepo | |
| 107 | + | |
| 108 | +# Import PlanOpticon meeting analysis | |
| 109 | +navegador planopticon ingest ./meeting-output/ | |
| 110 | +``` | |
| 111 | + | |
| 112 | +--- | |
| 70 | 113 | |
| 71 | 114 | ## Graph schema |
| 72 | 115 | |
| 73 | -**Nodes:** `Repository` · `File` · `Module` · `Class` · `Function` · `Method` · `Variable` · `Import` · `Decorator` | |
| 116 | +**Code nodes:** `Repository` · `File` · `Module` · `Class` · `Function` · `Method` · `Variable` · `Import` · `Decorator` | |
| 117 | + | |
| 118 | +**Knowledge nodes:** `Concept` · `Rule` · `Decision` · `Person` · `Domain` · `WikiPage` | |
| 74 | 119 | |
| 75 | -**Edges:** `CONTAINS` · `DEFINES` · `IMPORTS` · `CALLS` · `INHERITS` · `REFERENCES` · `DEPENDS_ON` | |
| 120 | +**Edges:** `CONTAINS` · `DEFINES` · `IMPORTS` · `CALLS` · `INHERITS` · `REFERENCES` · `DEPENDS_ON` · `GOVERNS` · `IMPLEMENTS` · `DOCUMENTS` · `ANNOTATES` | |
| 76 | 121 | |
| 77 | 122 | --- |
| 78 | 123 | |
| 79 | 124 | ## Storage |
| 80 | 125 | |
| 81 | -Navegador uses **FalkorDB** (property graph, Cypher queries). | |
| 82 | - | |
| 83 | 126 | | Mode | Backend | When to use | |
| 84 | 127 | |------|---------|-------------| |
| 85 | 128 | | Default | `falkordblite` (SQLite) | Local dev, zero infrastructure | |
| 86 | -| Production | Redis + FalkorDB module | Shared / persistent deployments | | |
| 129 | +| Production | Redis + FalkorDB module | Shared deployments, agent swarms | | |
| 87 | 130 | |
| 88 | 131 | ```python |
| 89 | 132 | from navegador.graph import GraphStore |
| 90 | 133 | |
| 91 | -# SQLite (default) | |
| 92 | -store = GraphStore.sqlite(".navegador/graph.db") | |
| 93 | - | |
| 94 | -# Redis | |
| 95 | -store = GraphStore.redis("redis://localhost:6379") | |
| 134 | +store = GraphStore.sqlite(".navegador/graph.db") # default | |
| 135 | +store = GraphStore.redis("redis://localhost:6379") # production | |
| 96 | 136 | ``` |
| 97 | 137 | |
| 98 | 138 | --- |
| 99 | 139 | |
| 100 | 140 | ## Language support |
| @@ -105,10 +145,46 @@ | ||
| 105 | 145 | | TypeScript / JavaScript | ✅ | |
| 106 | 146 | | Go | ✅ | |
| 107 | 147 | | Rust | ✅ | |
| 108 | 148 | | Java | ✅ | |
| 109 | 149 | |
| 150 | +--- | |
| 151 | + | |
| 152 | +## Installation | |
| 153 | + | |
| 154 | +### PyPI | |
| 155 | + | |
| 156 | +```bash | |
| 157 | +pip install navegador | |
| 158 | +``` | |
| 159 | + | |
| 160 | +### Standalone binaries | |
| 161 | + | |
| 162 | +No Python required — download prebuilt binaries from [GitHub Releases](https://github.com/ConflictHQ/navegador/releases): | |
| 163 | + | |
| 164 | +| Platform | Binary | | |
| 165 | +|----------|--------| | |
| 166 | +| macOS (Apple Silicon) | `navegador-macos-arm64` | | |
| 167 | +| macOS (Intel) | `navegador-macos-x86_64` | | |
| 168 | +| Linux | `navegador-linux-x86_64` | | |
| 169 | +| Windows | `navegador-windows-x86_64.exe` | | |
| 170 | + | |
| 171 | +### From source | |
| 172 | + | |
| 173 | +```bash | |
| 174 | +git clone https://github.com/ConflictHQ/navegador.git | |
| 175 | +cd navegador | |
| 176 | +pip install -e ".[dev]" | |
| 177 | +pytest | |
| 178 | +``` | |
| 179 | + | |
| 180 | +--- | |
| 181 | + | |
| 182 | +## Contributing | |
| 183 | + | |
| 184 | +See [CONTRIBUTING.md](.github/CONTRIBUTING.md). Bug reports and feature requests welcome via [GitHub Issues](https://github.com/ConflictHQ/navegador/issues). | |
| 185 | + | |
| 110 | 186 | --- |
| 111 | 187 | |
| 112 | 188 | ## License |
| 113 | 189 | |
| 114 | 190 | MIT — [CONFLICT](https://weareconflict.com) |
| 115 | 191 |
| --- README.md | |
| +++ README.md | |
| @@ -1,23 +1,38 @@ | |
| 1 | # Navegador |
| 2 | |
| 3 | **AST + knowledge graph context engine for AI coding agents.** |
| 4 | |
| 5 | Navegador parses your codebase into a property graph and makes it queryable. AI coding agents can ask "what calls this function?", "what does this file depend on?", or "show me everything related to auth" — and get structured, precise answers instead of raw file dumps. |
| 6 | |
| 7 | > *navegador* — Spanish for *navigator / sailor* |
| 8 | |
| 9 | [](https://github.com/ConflictHQ/navegador/actions/workflows/ci.yml) |
| 10 | [](https://pypi.org/project/navegador/) |
| 11 | [](LICENSE) |
| 12 | [](https://navegador.dev) |
| 13 | |
| 14 | --- |
| 15 | |
| 16 | ## Why |
| 17 | |
| 18 | AI coding agents load context by reading raw files. They don't know what calls what, what depends on what, or which 5 functions out of 500 are actually relevant. Navegador builds a structured map — then exposes it via MCP so any agent can navigate your code with precision. |
| 19 | |
| 20 | --- |
| 21 | |
| 22 | ## Quick start |
| 23 | |
| @@ -28,22 +43,25 @@ | |
| 28 | navegador ingest ./myrepo |
| 29 | |
| 30 | # Load context for a file |
| 31 | navegador context src/auth.py |
| 32 | |
| 33 | # Search for a symbol |
| 34 | navegador search "get_user" |
| 35 | |
| 36 | # Check graph stats |
| 37 | navegador stats |
| 38 | ``` |
| 39 | |
| 40 | --- |
| 41 | |
| 42 | ## MCP integration |
| 43 | |
| 44 | Add to your Claude / Cursor MCP config: |
| 45 | |
| 46 | ```json |
| 47 | { |
| 48 | "mcpServers": { |
| 49 | "navegador": { |
| @@ -65,36 +83,58 @@ | |
| 65 | | `search_symbols` | Fuzzy search for functions/classes by name | |
| 66 | | `query_graph` | Raw Cypher passthrough | |
| 67 | | `graph_stats` | Node and edge counts | |
| 68 | |
| 69 | --- |
| 70 | |
| 71 | ## Graph schema |
| 72 | |
| 73 | **Nodes:** `Repository` · `File` · `Module` · `Class` · `Function` · `Method` · `Variable` · `Import` · `Decorator` |
| 74 | |
| 75 | **Edges:** `CONTAINS` · `DEFINES` · `IMPORTS` · `CALLS` · `INHERITS` · `REFERENCES` · `DEPENDS_ON` |
| 76 | |
| 77 | --- |
| 78 | |
| 79 | ## Storage |
| 80 | |
| 81 | Navegador uses **FalkorDB** (property graph, Cypher queries). |
| 82 | |
| 83 | | Mode | Backend | When to use | |
| 84 | |------|---------|-------------| |
| 85 | | Default | `falkordblite` (SQLite) | Local dev, zero infrastructure | |
| 86 | | Production | Redis + FalkorDB module | Shared / persistent deployments | |
| 87 | |
| 88 | ```python |
| 89 | from navegador.graph import GraphStore |
| 90 | |
| 91 | # SQLite (default) |
| 92 | store = GraphStore.sqlite(".navegador/graph.db") |
| 93 | |
| 94 | # Redis |
| 95 | store = GraphStore.redis("redis://localhost:6379") |
| 96 | ``` |
| 97 | |
| 98 | --- |
| 99 | |
| 100 | ## Language support |
| @@ -105,10 +145,46 @@ | |
| 105 | | TypeScript / JavaScript | ✅ | |
| 106 | | Go | ✅ | |
| 107 | | Rust | ✅ | |
| 108 | | Java | ✅ | |
| 109 | |
| 110 | --- |
| 111 | |
| 112 | ## License |
| 113 | |
| 114 | MIT — [CONFLICT](https://weareconflict.com) |
| 115 |
| --- README.md | |
| +++ README.md | |
| @@ -1,23 +1,38 @@ | |
| 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 | [](https://github.com/ConflictHQ/navegador/actions/workflows/ci.yml) |
| 10 | [](https://pypi.org/project/navegador/) |
| 11 | [](https://pypi.org/project/navegador/) |
| 12 | [](LICENSE) |
| 13 | [](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 | |
| @@ -28,22 +43,25 @@ | |
| 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": { |
| @@ -65,36 +83,58 @@ | |
| 83 | | `search_symbols` | Fuzzy search for functions/classes by name | |
| 84 | | `query_graph` | Raw Cypher passthrough | |
| 85 | | `graph_stats` | Node and edge counts | |
| 86 | |
| 87 | --- |
| 88 | |
| 89 | ## Knowledge layer |
| 90 | |
| 91 | Beyond code structure, navegador stores what your team knows: |
| 92 | |
| 93 | ```bash |
| 94 | # Record an architectural decision |
| 95 | navegador add decision "Use FalkorDB for graph storage" \ |
| 96 | --rationale "Cypher queries, SQLite-backed zero-infra mode" |
| 97 | |
| 98 | # Define a business concept and link it to code |
| 99 | navegador add concept PaymentProcessing |
| 100 | navegador annotate PaymentProcessing --function process_charge |
| 101 | |
| 102 | # Add a rule |
| 103 | navegador add rule "All writes must go through the service layer" |
| 104 | |
| 105 | # Ingest your GitHub wiki |
| 106 | navegador wiki ingest --repo myorg/myrepo |
| 107 | |
| 108 | # Import PlanOpticon meeting analysis |
| 109 | navegador planopticon ingest ./meeting-output/ |
| 110 | ``` |
| 111 | |
| 112 | --- |
| 113 | |
| 114 | ## Graph schema |
| 115 | |
| 116 | **Code nodes:** `Repository` · `File` · `Module` · `Class` · `Function` · `Method` · `Variable` · `Import` · `Decorator` |
| 117 | |
| 118 | **Knowledge nodes:** `Concept` · `Rule` · `Decision` · `Person` · `Domain` · `WikiPage` |
| 119 | |
| 120 | **Edges:** `CONTAINS` · `DEFINES` · `IMPORTS` · `CALLS` · `INHERITS` · `REFERENCES` · `DEPENDS_ON` · `GOVERNS` · `IMPLEMENTS` · `DOCUMENTS` · `ANNOTATES` |
| 121 | |
| 122 | --- |
| 123 | |
| 124 | ## Storage |
| 125 | |
| 126 | | Mode | Backend | When to use | |
| 127 | |------|---------|-------------| |
| 128 | | Default | `falkordblite` (SQLite) | Local dev, zero infrastructure | |
| 129 | | Production | Redis + FalkorDB module | Shared deployments, agent swarms | |
| 130 | |
| 131 | ```python |
| 132 | from navegador.graph import GraphStore |
| 133 | |
| 134 | store = GraphStore.sqlite(".navegador/graph.db") # default |
| 135 | store = GraphStore.redis("redis://localhost:6379") # production |
| 136 | ``` |
| 137 | |
| 138 | --- |
| 139 | |
| 140 | ## Language support |
| @@ -105,10 +145,46 @@ | |
| 145 | | TypeScript / JavaScript | ✅ | |
| 146 | | Go | ✅ | |
| 147 | | Rust | ✅ | |
| 148 | | Java | ✅ | |
| 149 | |
| 150 | --- |
| 151 | |
| 152 | ## Installation |
| 153 | |
| 154 | ### PyPI |
| 155 | |
| 156 | ```bash |
| 157 | pip install navegador |
| 158 | ``` |
| 159 | |
| 160 | ### Standalone binaries |
| 161 | |
| 162 | No Python required — download prebuilt binaries from [GitHub Releases](https://github.com/ConflictHQ/navegador/releases): |
| 163 | |
| 164 | | Platform | Binary | |
| 165 | |----------|--------| |
| 166 | | macOS (Apple Silicon) | `navegador-macos-arm64` | |
| 167 | | macOS (Intel) | `navegador-macos-x86_64` | |
| 168 | | Linux | `navegador-linux-x86_64` | |
| 169 | | Windows | `navegador-windows-x86_64.exe` | |
| 170 | |
| 171 | ### From source |
| 172 | |
| 173 | ```bash |
| 174 | git clone https://github.com/ConflictHQ/navegador.git |
| 175 | cd navegador |
| 176 | pip install -e ".[dev]" |
| 177 | pytest |
| 178 | ``` |
| 179 | |
| 180 | --- |
| 181 | |
| 182 | ## Contributing |
| 183 | |
| 184 | See [CONTRIBUTING.md](.github/CONTRIBUTING.md). Bug reports and feature requests welcome via [GitHub Issues](https://github.com/ConflictHQ/navegador/issues). |
| 185 | |
| 186 | --- |
| 187 | |
| 188 | ## License |
| 189 | |
| 190 | MIT — [CONFLICT](https://weareconflict.com) |
| 191 |