{"id":41585287,"url":"https://github.com/biuld/naviscope","last_synced_at":"2026-02-01T19:00:47.276Z","repository":{"id":333191037,"uuid":"1136507123","full_name":"biuld/naviscope","owner":"biuld","description":"Unified Code Knowledge Graph Engine for AI Agents \u0026 Developers","archived":false,"fork":false,"pushed_at":"2026-02-01T05:42:39.000Z","size":660,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-01T08:59:11.790Z","etag":null,"topics":["gradle","java","java-lsp","knowledge-graph","llm-agent","lsp","mcp","rag","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/biuld.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-17T20:16:15.000Z","updated_at":"2026-01-26T15:41:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/biuld/naviscope","commit_stats":null,"previous_names":["biuld/naviscope"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/biuld/naviscope","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biuld%2Fnaviscope","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biuld%2Fnaviscope/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biuld%2Fnaviscope/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biuld%2Fnaviscope/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/biuld","download_url":"https://codeload.github.com/biuld/naviscope/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/biuld%2Fnaviscope/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28986332,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T18:17:03.387Z","status":"ssl_error","status_checked_at":"2026-02-01T18:16:57.287Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gradle","java","java-lsp","knowledge-graph","llm-agent","lsp","mcp","rag","rust"],"created_at":"2026-01-24T09:00:39.806Z","updated_at":"2026-02-01T19:00:47.270Z","avatar_url":"https://github.com/biuld.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Naviscope\n\n**Unified Code Knowledge Graph Engine for AI Agents \u0026 Developers**\n\nNaviscope bridges the gap between AI and IDEs. It builds a comprehensive, graph-based representation of your codebase (connecting micro-level semantics like type relationships and inheritance with macro-level structures) that powers both **LLM agents** (via MCP) and **code editors** (via LSP).\n\nUnlike traditional tools that maintain separate indexes for different purposes, Naviscope provides a **single, unified knowledge graph**, ensuring that what AI agents see is exactly what developers navigate.\n\n## 💡 Why Naviscope?\n\n| Feature | Traditional Tools | Naviscope |\n| :--- | :--- | :--- |\n| **Context** | Text-based (regex/grep) | **Graph-based** (structural/semantic) |\n| **Performance** | High latency (JVM based) | **Instant** (Rust native, Zero-JVM overhead) |\n| **Consistency** | Fragmented (Agent vs IDE) | **Unified** (Same graph for both) |\n| **Resilience** | Blocks on errors/missing deps | **Robust** (Works with partial/broken code) |\n\n## 🌟 Capabilities\n\n### 🤖 For AI Agents (MCP Support)\nNaviscope implements the [Model Context Protocol](https://modelcontextprotocol.io/), giving LLMs \"X-ray vision\" into your code structure.\n\n- **`get_guide`**: Call this first! Get a comprehensive guide on how to use Naviscope tools.\n- **`ls`**: Hierarchical exploration of packages, modules, and fields.\n- **`find`**: Precise symbol search (find \"Class definitions\", not just string matches).\n- **`cat`**: Retrieve definition, source code, and metadata for any symbol.\n- **`deps`**: Analyze incoming/outgoing dependencies and relationships (inheritance, type usage, etc.).\n\n### 👨‍💻 For Developers (LSP Support)\nA lightweight, lightning-fast alternative to standard language servers (like JDTLS).\n\n- **Navigation**: Go to Definition, Find References, Go to Implementation.\n- **Understanding**: Hover documentation, Document Highlights.\n- **Hierarchy**: Call Hierarchy, Type Hierarchy.\n- **Speed**: Works immediately on large projects without long indexing pauses.\n\n## 🏗️ Architecture\n\n```mermaid\ngraph TD\n    %% Styles\n    classDef interface fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,rx:5,ry:5\n    classDef runtime fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,rx:5,ry:5\n    classDef language fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,rx:5,ry:5\n    classDef core fill:#fff3e0,stroke:#ef6c00,stroke-width:2px,rx:5,ry:5\n    classDef api fill:#fafafa,stroke:#616161,stroke-width:2px,rx:5,ry:5\n\n    subgraph Interfaces [Interface Layer]\n        CLI[\"naviscope-cli\u003cbr/\u003e(Shell \u0026 Main)\"]:::interface\n        LSP[\"naviscope-lsp\u003cbr/\u003e(LSP Server)\"]:::interface\n        MCP[\"naviscope-mcp\u003cbr/\u003e(MCP Server)\"]:::interface\n    end\n\n    subgraph Orchestration [Runtime Layer]\n        Runtime[\"naviscope-runtime\u003cbr/\u003e(Engine Orchestrator)\"]:::runtime\n    end\n\n    subgraph Strategies [Language Layer]\n        Java[\"naviscope-java\u003cbr/\u003e(Java Analysis)\"]:::language\n        Gradle[\"naviscope-gradle\u003cbr/\u003e(Gradle Analysis)\"]:::language\n    end\n\n    subgraph Engine [Core Layer]\n        Core[\"naviscope-core\u003cbr/\u003e(Graph, Index \u0026 IO)\"]:::core\n    end\n\n    subgraph Foundation [API Layer]\n        API[\"naviscope-api\u003cbr/\u003e(Common Traits \u0026 Models)\"]:::api\n    end\n\n    %% Crate Dependencies\n    CLI --\u003e LSP\n    CLI --\u003e MCP\n    CLI --\u003e Runtime\n    CLI --\u003e API\n\n    LSP --\u003e MCP\n    LSP --\u003e API\n\n    MCP --\u003e API\n\n    Runtime --\u003e Java\n    Runtime --\u003e Gradle\n    Runtime --\u003e Core\n    Runtime --\u003e API\n\n    Java --\u003e Core\n    Java --\u003e API\n\n    Gradle --\u003e Core\n    Gradle --\u003e API\n\n    Core --\u003e API\n```\n\nNaviscope is built on a **layered crate architecture** that separates concerns across multiple Rust crates:\n\n- **Interface Layer** (`naviscope-cli`, `naviscope-lsp`, `naviscope-mcp`): Entry points for different use cases (CLI shell, LSP for editors, MCP for AI agents).\n- **Runtime Layer** (`naviscope-runtime`): Orchestrates the engine assembly, registering language plugins and providing a unified factory.\n- **Language Layer** (`naviscope-java`, `naviscope-gradle`): Language-specific analysis plugins that parse and resolve symbols.\n- **Core Layer** (`naviscope-core`): The heart of the system - graph storage, indexing, file scanning, and persistence.\n- **API Layer** (`naviscope-api`): Common traits and models shared across all crates, ensuring a consistent interface.\n\nThe core is a language-agnostic graph structure populated by language-specific strategies (currently Java/Gradle via Tree-sitter), exposing a unified query engine to both AI agents and developer tools.\n\n### 🔍 Reference Discovery Strategy\n\nNaviscope uses a **two-phase reference discovery** approach for optimal performance:\n\n1. **Meso-level (Coarse Filtering)**: Uses an inverted `reference_index` (token → files) to quickly identify candidate files that likely contain references to a symbol. This index is built during parsing by extracting all identifier tokens from source files.\n\n2. **Micro-level (Precise Analysis)**: For each candidate file, uses Tree-sitter to parse and verify actual symbol occurrences, ensuring accurate reference locations.\n\nThis hybrid approach combines the speed of inverted indexing with the precision of syntax-aware parsing, enabling fast reference discovery even in large codebases.\n\n## 🚀 Quick Start\n\n### Prerequisites\n- Rust (2024 edition)\n- C Compiler (required for compiling Tree-sitter grammars)\n\n### Installation from source code\n\n```bash\n# 1. Clone \u0026 Update Submodules (Required for tree-sitter grammars)\ngit clone https://github.com/biuld/naviscope.git\ncd naviscope\ngit submodule update --init --recursive\n\n# 2. Install the Naviscope CLI\ncargo install --path crates/cli\n\n# 3. (Optional) Build the VS Code Extension\ncd editors/vscode\nnpm install\nnpm run package\n# Then install the generated .vsix file in VS Code\n```\n\n### Usage\n\n#### CLI Commands\n- `naviscope index \u003cPATH\u003e`: Build a persistent index for a project.\n- `naviscope shell [PATH]`: Start an interactive shell to query the graph.\n- `naviscope watch \u003cPATH\u003e`: Start a background service to keep the index updated.\n- `naviscope clear [PATH]`: Clear built indices (or all indices if path omitted).\n- `naviscope mcp`: Start the MCP server.\n- `naviscope lsp`: Start the LSP server.\n\n#### Configure in Cursor (for AI Agents)\n1.  Open **Cursor Settings** (Cmd + Shift + J) -\u003e **Features** -\u003e **MCP**.\n2.  Click **+ Add New MCP Server**.\n3.  Configure:\n    - **Name**: `Naviscope`\n    - **Type**: `command`\n    - **Command**: `naviscope mcp`\n\n#### Configure in VS Code / NeoVim (for LSP)\n- **VS Code**: Install the extension built in step 3.\n- **Other Clients**: Point your LSP client to run `naviscope lsp`.\n\n## 🛠️ Query DSL (Interactive Shell)\n\nThe `naviscope shell` provides a Unix-like experience for exploring the Code Knowledge Graph:\n\n```bash\n# Change current context to a package or class\ncd \"com.example.service\"\n\n# List members in current context\nls\n\n# List with detailed information\nls -l\n\n# Find all classes named 'UserService'\nfind \"UserService\" --kind class\n\n# Inspect full details of a symbol (source code, metadata)\ncat \"UserService\"\n\n# Find who references current symbol?\ndeps --rev\n\n# Print current FQN context\npwd\n\n# Clear screen\nclear\n```\n\n## 🔗 Graph Relationships\n\nNaviscope tracks the following relationship types in the knowledge graph:\n\n- **Structural**: `Contains` (package → class, class → method, etc.)\n- **Inheritance**: `InheritsFrom`, `Implements`\n- **Type Usage**: `TypedAs` (field/variable → type)\n- **Annotations**: `DecoratedBy` (class/method → annotation)\n- **Build System**: `UsesDependency` (project → dependency)\n\nReference discovery (method calls, instantiations) is handled efficiently through the `reference_index` + Tree-sitter two-phase approach, avoiding the need to store explicit call edges for every reference.\n\n## 📈 Roadmap\n\n- [x] **Core**: Graph Storage (`petgraph`), Parallel Indexing, Real-time Updates (`notify`).\n- [x] **Languages**: Java \u0026 Gradle (Tree-sitter driven).\n- [x] **Interfaces**: CLI Shell, MCP Server, LSP Server.\n- [x] **Editors**: VS Code Extension.\n- [x] **Reference Discovery**: Two-phase approach (reference_index + Tree-sitter).\n- [ ] **Upcoming**: Maven Support, Python/Rust Language Strategies.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiuld%2Fnaviscope","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbiuld%2Fnaviscope","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbiuld%2Fnaviscope/lists"}