navcode 0.1.0__tar.gz

navcode-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Noman Rafique
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

navcode-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+recursive-include navcode *.py

navcode-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: navcode
+Version: 0.1.0
+Summary: Codebase intelligence layer for AI coding agents — 80-90% token reduction
+Author-email: Noman Rafique <nomanrafique01@gmail.com>
+License-Expression: MIT
+Keywords: ai,agents,context,codebase,tokens,mcp,claude,cursor
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: loguru>=0.7.2
+Requires-Dist: watchdog>=4.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: onnxruntime>=1.18.0
+Requires-Dist: tokenizers>=0.19.0
+Requires-Dist: networkx>=3.3.0
+Requires-Dist: tree-sitter>=0.22.0
+Requires-Dist: fastmcp>=0.4.0
+Requires-Dist: SQLAlchemy>=2.0.0
+Requires-Dist: tree-sitter-python>=0.21.0
+Requires-Dist: tree-sitter-javascript>=0.21.0
+Requires-Dist: tree-sitter-typescript>=0.21.0
+Requires-Dist: tree-sitter-java>=0.21.0
+Requires-Dist: tree-sitter-cpp>=0.22.0
+Requires-Dist: tree-sitter-c>=0.21.0
+Requires-Dist: tree-sitter-go>=0.21.0
+Requires-Dist: tree-sitter-rust>=0.21.0
+Requires-Dist: tree-sitter-ruby>=0.21.0
+Requires-Dist: tree-sitter-c-sharp>=0.21.0
+Requires-Dist: tree-sitter-php>=0.22.0
+Requires-Dist: tree-sitter-swift>=0.6.0
+Requires-Dist: tree-sitter-kotlin>=0.3.0
+Requires-Dist: tree-sitter-scala>=0.21.0
+Requires-Dist: tree-sitter-haskell>=0.21.0
+Requires-Dist: tree-sitter-lua>=0.1.0
+Requires-Dist: tree-sitter-r>=0.1.0
+Requires-Dist: tree-sitter-bash>=0.21.0
+Requires-Dist: tree-sitter-html>=0.20.0
+Requires-Dist: tree-sitter-css>=0.21.0
+Requires-Dist: tree-sitter-json>=0.21.0
+Requires-Dist: tree-sitter-yaml>=0.6.0
+Requires-Dist: tree-sitter-toml>=0.6.0
+Requires-Dist: tree-sitter-markdown>=0.3.0
+Requires-Dist: tree-sitter-sql>=0.2.0
+Requires-Dist: tree-sitter-dockerfile>=0.2.0
+Requires-Dist: tree-sitter-regex>=0.21.0
+Dynamic: license-file
+
+# navcode
+> Codebase intelligence layer for AI coding agents
+
+## Install
+```bash
+pip install navcode
+```
+
+## Usage
+```bash
+navcode init --claude
+navcode init --cursor
+navcode init --bob
+navcode init --auto
+```
+
+## Supported Agents
+Claude Code, Cursor, IBM Bob, Codex, Copilot,
+Kimi, Antigravity, Windsurf, Continue
+
+## How it works
+navcode indexes your codebase locally and feeds only
+relevant context to AI agents — reducing token usage by 80-90%.
+
+Built by Nythris Studio

navcode-0.1.0/README.md

@@ -0,0 +1,25 @@
+# navcode
+> Codebase intelligence layer for AI coding agents
+
+## Install
+```bash
+pip install navcode
+```
+
+## Usage
+```bash
+navcode init --claude
+navcode init --cursor
+navcode init --bob
+navcode init --auto
+```
+
+## Supported Agents
+Claude Code, Cursor, IBM Bob, Codex, Copilot,
+Kimi, Antigravity, Windsurf, Continue
+
+## How it works
+navcode indexes your codebase locally and feeds only
+relevant context to AI agents — reducing token usage by 80-90%.
+
+Built by Nythris Studio

navcode-0.1.0/navcode/__init__.py

@@ -0,0 +1,22 @@
+from navcode._bootstrap import ensure_model
+from loguru import logger
+from pathlib import Path
+
+__version__ = "0.1.0"
+
+ensure_model()
+
+
+def _setup_logging() -> None:
+    log_dir = Path.cwd() / ".codenav"
+    if log_dir.exists():
+        logger.add(
+            log_dir / "navcode.log",
+            rotation="5 MB",
+            retention="7 days",
+            level="INFO",
+            format="{time:YYYY-MM-DD HH:mm:ss} | {level} | {message}",
+        )
+
+
+_setup_logging()

navcode-0.1.0/navcode/_bootstrap.py

@@ -0,0 +1,122 @@
+"""Bootstrap utilities — ensures the ONNX embedding model is present on disk."""
+
+from pathlib import Path
+
+import httpx
+from loguru import logger
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import (
+    BarColumn,
+    DownloadColumn,
+    Progress,
+    TextColumn,
+    TimeRemainingColumn,
+    TransferSpeedColumn,
+)
+
+_HF_BASE: str = (
+    "https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main"
+)
+MODEL_URL: str = f"{_HF_BASE}/onnx/model_quantized.onnx"
+MODEL_PATH: Path = Path.home() / ".navcode" / "models" / "model_quantized.onnx"
+
+# Tokenizer files required by EmbeddingsEngine
+_TOKENIZER_FILES: list[str] = [
+    "tokenizer.json",
+    "tokenizer_config.json",
+    "vocab.txt",
+    "special_tokens_map.json",
+]
+
+_console = Console()
+
+
+def _download_file(url: str, dest: Path, label: str) -> None:
+    """Stream *url* to *dest* with a Rich progress bar.
+
+    Raises:
+        httpx.HTTPError: on any HTTP-level failure.
+    """
+    with httpx.stream("GET", url, follow_redirects=True, timeout=60) as response:
+        response.raise_for_status()
+        total = int(response.headers.get("content-length", 0)) or None
+
+        with Progress(
+            TextColumn(f"[bold blue]{label}[/bold blue]"),
+            BarColumn(),
+            DownloadColumn(),
+            TransferSpeedColumn(),
+            TimeRemainingColumn(),
+            console=_console,
+            transient=True,
+        ) as progress:
+            task = progress.add_task("download", total=total)
+            with dest.open("wb") as fh:
+                for chunk in response.iter_bytes(chunk_size=8192):
+                    fh.write(chunk)
+                    progress.update(task, advance=len(chunk))
+
+
+def ensure_model() -> None:
+    """Ensure the quantised ONNX embedding model exists locally.
+
+    If the model file is already present at ``~/.navcode/models/model_quantized.onnx``
+    this function returns immediately.  On first run it streams the file from
+    HuggingFace, displaying a Rich progress bar.  Network failures are caught,
+    shown as a Rich warning panel, and silently swallowed so the rest of navcode
+    can still load (the model will be re-attempted on ``navcode init``).
+    """
+    if MODEL_PATH.exists():
+        logger.debug("ONNX model already present at {}", MODEL_PATH)
+    else:
+        MODEL_PATH.parent.mkdir(parents=True, exist_ok=True)
+        logger.info("ONNX model not found — downloading from HuggingFace…")
+
+        try:
+            _download_file(MODEL_URL, MODEL_PATH, "Downloading model")
+            logger.info("Model saved to {}", MODEL_PATH)
+        except httpx.HTTPError as exc:
+            _console.print(
+                Panel(
+                    f"[yellow]navcode[/yellow] could not download the embedding model.\n"
+                    f"[dim]{exc}[/dim]\n\n"
+                    "navcode will still load — the model will be downloaded on first "
+                    "[cyan]navcode init[/cyan].",
+                    title="[bold yellow]⚠ Model download skipped[/bold yellow]",
+                    border_style="yellow",
+                )
+            )
+            logger.warning("Model download failed: {}", exc)
+
+    # Ensure tokenizer files are present alongside the model
+    _ensure_tokenizer_files()
+
+
+def _ensure_tokenizer_files() -> None:
+    """Download any missing tokenizer files from HuggingFace."""
+    models_dir = MODEL_PATH.parent
+    models_dir.mkdir(parents=True, exist_ok=True)
+
+    for filename in _TOKENIZER_FILES:
+        dest = models_dir / filename
+        if dest.exists():
+            logger.debug("Tokenizer file already present: {}", filename)
+            continue
+
+        url = f"{_HF_BASE}/{filename}"
+        logger.info("Tokenizer file not found — downloading: {}", filename)
+        try:
+            _download_file(url, dest, f"Downloading {filename}")
+            logger.info("Saved {}", dest)
+        except httpx.HTTPError as exc:
+            _console.print(
+                Panel(
+                    f"[yellow]navcode[/yellow] could not download [cyan]{filename}[/cyan].\n"
+                    f"[dim]{exc}[/dim]\n\n"
+                    "Semantic search may be unavailable until this file is present.",
+                    title="[bold yellow]⚠ Tokenizer file download skipped[/bold yellow]",
+                    border_style="yellow",
+                )
+            )
+            logger.warning("Tokenizer file download failed ({}): {}", filename, exc)

navcode-0.1.0/navcode/adapters/__init__.py

@@ -0,0 +1,36 @@
+"""navcode agent adapters — one per supported AI coding agent."""
+
+from navcode.adapters.claude import ClaudeAdapter
+from navcode.adapters.cursor import CursorAdapter
+from navcode.adapters.codex import CodexAdapter
+from navcode.adapters.copilot import CopilotAdapter
+from navcode.adapters.bob import BobAdapter
+from navcode.adapters.kimi import KimiAdapter
+from navcode.adapters.antigravity import AntigravityAdapter
+from navcode.adapters.windsurf import WindsurfAdapter
+from navcode.adapters.continue_ import ContinueAdapter
+
+ALL_ADAPTERS = {
+    "claude":      ClaudeAdapter,
+    "cursor":      CursorAdapter,
+    "codex":       CodexAdapter,
+    "copilot":     CopilotAdapter,
+    "bob":         BobAdapter,
+    "kimi":        KimiAdapter,
+    "antigravity": AntigravityAdapter,
+    "windsurf":    WindsurfAdapter,
+    "continue":    ContinueAdapter,
+}
+
+__all__ = [
+    "ClaudeAdapter",
+    "CursorAdapter",
+    "CodexAdapter",
+    "CopilotAdapter",
+    "BobAdapter",
+    "KimiAdapter",
+    "AntigravityAdapter",
+    "WindsurfAdapter",
+    "ContinueAdapter",
+    "ALL_ADAPTERS",
+]

navcode-0.1.0/navcode/adapters/antigravity.py

@@ -0,0 +1,31 @@
+"""Antigravity adapter."""
+
+from pathlib import Path
+
+from navcode.adapters.base import BaseAdapter
+
+
+class AntigravityAdapter(BaseAdapter):
+
+    NAME = "Antigravity"
+    BINARY = "antigravity"
+    CONFIG_DIR = "~/.antigravity"
+    PROJECT_DIR = ".antigravity"
+    PROCESS_NAME = "antigravity"
+    INSTRUCTION_FILE = ".antigravity/instructions.md"
+
+    def install(self) -> None:
+        self._write_instruction_file(
+            self.project_root / ".antigravity" / "instructions.md",
+            self._instruction_content(),
+        )
+        self._inject_mcp_config(
+            Path.home() / ".antigravity" / "mcp.json"
+        )
+
+    def is_detected(self) -> bool:
+        return (
+            self._detect_binary()
+            or self._detect_config_dir()
+            or self._detect_project_dir()
+        )

navcode-0.1.0/navcode/adapters/base.py

@@ -0,0 +1,100 @@
+"""Abstract base class for all navcode agent adapters."""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+
+class BaseAdapter(ABC):
+
+    # Override these in every adapter
+    NAME: str = ""
+    BINARY: str = ""
+    CONFIG_DIR: str = ""
+    PROJECT_DIR: str = ""
+    PROCESS_NAME: str | None = None
+    INSTRUCTION_FILE: str = ""
+
+    def __init__(self, project_root: Path):
+        self.project_root = project_root
+        self.codenav_dir = project_root / ".codenav"
+
+    @abstractmethod
+    def install(self) -> None:
+        """Create all required files for this agent."""
+        pass
+
+    @abstractmethod
+    def is_detected(self) -> bool:
+        """Return True if this agent is installed on the system."""
+        pass
+
+    def _write_instruction_file(self, path: Path, content: str) -> None:
+        """Write instruction file, create parent dirs if needed."""
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+
+    def _inject_mcp_config(self, config_path: Path) -> None:
+        """Inject navcode MCP entry into agent JSON config."""
+        import json
+
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+
+        existing = {}
+        if config_path.exists():
+            try:
+                existing = json.loads(config_path.read_text())
+            except json.JSONDecodeError:
+                pass
+
+        existing.setdefault("mcpServers", {})
+        existing["mcpServers"]["navcode"] = {
+            "command": "navcode",
+            "args": ["mcp-serve"],
+            "cwd": str(self.project_root),
+        }
+        config_path.write_text(
+            json.dumps(existing, indent=2),
+            encoding="utf-8",
+        )
+
+    def _detect_binary(self) -> bool:
+        import shutil
+
+        return shutil.which(self.BINARY) is not None
+
+    def _detect_config_dir(self) -> bool:
+        return Path.home().joinpath(
+            self.CONFIG_DIR.lstrip("~/")
+        ).exists()
+
+    def _detect_project_dir(self) -> bool:
+        return (self.project_root / self.PROJECT_DIR).exists()
+
+    def _instruction_content(self) -> str:
+        return f"""# navcode — Active
+
+## Rules for {self.NAME}
+
+NEVER use read_file or list_directory to explore the codebase.
+ALWAYS start every task with navcode_get_context(task=<your task>).
+Work ONLY within files and symbols navcode returns.
+If you need more: call navcode_expand_context(file_path, reason).
+
+## Available MCP Tools
+
+| Tool | When to use |
+|---|---|
+| navcode_get_context(task) | FIRST call — always |
+| navcode_expand_context(file, reason) | Need more from one file |
+| navcode_get_callers(function) | Understand blast radius |
+| navcode_get_deps(file) | See what a file imports |
+| navcode_search(query) | Find where something is defined |
+| navcode_get_structure() | Architectural overview |
+| navcode_stats() | Index health check |
+
+## Why
+navcode has pre-indexed this codebase.
+Using it saves 80-90% tokens vs raw file reads.
+
+Built by Nythris Studio
+"""

navcode-0.1.0/navcode/adapters/bob.py

@@ -0,0 +1,33 @@
+"""IBM Bob adapter."""
+
+from pathlib import Path
+
+from navcode.adapters.base import BaseAdapter
+
+
+class BobAdapter(BaseAdapter):
+
+    NAME = "IBM Bob"
+    BINARY = "bob"
+    CONFIG_DIR = "~/.bob"
+    PROJECT_DIR = ".bob"
+    PROCESS_NAME = "bob-agent"
+    INSTRUCTION_FILE = ".bob/instructions.md"
+
+    def install(self) -> None:
+        # 1. Write .bob/instructions.md
+        self._write_instruction_file(
+            self.project_root / ".bob" / "instructions.md",
+            self._instruction_content(),
+        )
+        # 2. Inject MCP into ~/.bob/mcp.json
+        self._inject_mcp_config(
+            Path.home() / ".bob" / "mcp.json"
+        )
+
+    def is_detected(self) -> bool:
+        return (
+            self._detect_binary()
+            or self._detect_config_dir()
+            or self._detect_project_dir()
+        )

navcode-0.1.0/navcode/adapters/claude.py

@@ -0,0 +1,33 @@
+"""Claude Code adapter."""
+
+from pathlib import Path
+
+from navcode.adapters.base import BaseAdapter
+
+
+class ClaudeAdapter(BaseAdapter):
+
+    NAME = "Claude Code"
+    BINARY = "claude"
+    CONFIG_DIR = "~/.claude"
+    PROJECT_DIR = "CLAUDE.md"
+    PROCESS_NAME = None
+    INSTRUCTION_FILE = "CLAUDE.md"
+
+    def install(self) -> None:
+        # 1. Write CLAUDE.md to project root
+        self._write_instruction_file(
+            self.project_root / "CLAUDE.md",
+            self._instruction_content(),
+        )
+        # 2. Inject MCP into ~/.claude/mcp.json
+        self._inject_mcp_config(
+            Path.home() / ".claude" / "mcp.json"
+        )
+
+    def is_detected(self) -> bool:
+        return (
+            self._detect_binary()
+            or self._detect_config_dir()
+            or self._detect_project_dir()
+        )

navcode-0.1.0/navcode/adapters/codex.py

@@ -0,0 +1,33 @@
+"""Codex CLI adapter."""
+
+from pathlib import Path
+
+from navcode.adapters.base import BaseAdapter
+
+
+class CodexAdapter(BaseAdapter):
+
+    NAME = "Codex CLI"
+    BINARY = "codex"
+    CONFIG_DIR = "~/.codex"
+    PROJECT_DIR = "AGENTS.md"
+    PROCESS_NAME = None
+    INSTRUCTION_FILE = "AGENTS.md"
+
+    def install(self) -> None:
+        # 1. Write AGENTS.md
+        self._write_instruction_file(
+            self.project_root / "AGENTS.md",
+            self._instruction_content(),
+        )
+        # 2. Inject MCP into ~/.codex/config.json
+        self._inject_mcp_config(
+            Path.home() / ".codex" / "config.json"
+        )
+
+    def is_detected(self) -> bool:
+        return (
+            self._detect_binary()
+            or self._detect_config_dir()
+            or self._detect_project_dir()
+        )

navcode-0.1.0/navcode/adapters/continue_.py

@@ -0,0 +1,31 @@
+"""Continue adapter."""
+
+from pathlib import Path
+
+from navcode.adapters.base import BaseAdapter
+
+
+class ContinueAdapter(BaseAdapter):
+
+    NAME = "Continue"
+    BINARY = "continue"
+    CONFIG_DIR = "~/.continue"
+    PROJECT_DIR = ".continue"
+    PROCESS_NAME = None
+    INSTRUCTION_FILE = ".continue/navcode.md"
+
+    def install(self) -> None:
+        self._write_instruction_file(
+            self.project_root / ".continue" / "navcode.md",
+            self._instruction_content(),
+        )
+        self._inject_mcp_config(
+            Path.home() / ".continue" / "config.json"
+        )
+
+    def is_detected(self) -> bool:
+        return (
+            self._detect_binary()
+            or self._detect_config_dir()
+            or self._detect_project_dir()
+        )

navcode-0.1.0/navcode/adapters/copilot.py

@@ -0,0 +1,24 @@
+"""GitHub Copilot adapter."""
+
+from navcode.adapters.base import BaseAdapter
+
+
+class CopilotAdapter(BaseAdapter):
+
+    NAME = "GitHub Copilot"
+    BINARY = "gh"
+    CONFIG_DIR = "~/.config/gh"
+    PROJECT_DIR = ".github"
+    PROCESS_NAME = None
+    INSTRUCTION_FILE = ".github/copilot-instructions.md"
+
+    def install(self) -> None:
+        # Write .github/copilot-instructions.md
+        self._write_instruction_file(
+            self.project_root / ".github" / "copilot-instructions.md",
+            self._instruction_content(),
+        )
+        # No MCP config for Copilot yet
+
+    def is_detected(self) -> bool:
+        return self._detect_binary() or self._detect_project_dir()

navcode-0.1.0/navcode/adapters/cursor.py

@@ -0,0 +1,33 @@
+"""Cursor adapter."""
+
+from pathlib import Path
+
+from navcode.adapters.base import BaseAdapter
+
+
+class CursorAdapter(BaseAdapter):
+
+    NAME = "Cursor"
+    BINARY = "cursor"
+    CONFIG_DIR = "~/.cursor"
+    PROJECT_DIR = ".cursor"
+    PROCESS_NAME = "cursor"
+    INSTRUCTION_FILE = ".cursor/rules/navcode.md"
+
+    def install(self) -> None:
+        # 1. Write .cursor/rules/navcode.md
+        self._write_instruction_file(
+            self.project_root / ".cursor" / "rules" / "navcode.md",
+            self._instruction_content(),
+        )
+        # 2. Inject MCP into .cursor/mcp.json
+        self._inject_mcp_config(
+            self.project_root / ".cursor" / "mcp.json"
+        )
+
+    def is_detected(self) -> bool:
+        return (
+            self._detect_binary()
+            or self._detect_config_dir()
+            or self._detect_project_dir()
+        )

navcode-0.1.0/navcode/adapters/kimi.py

@@ -0,0 +1,31 @@
+"""Kimi Code adapter."""
+
+from pathlib import Path
+
+from navcode.adapters.base import BaseAdapter
+
+
+class KimiAdapter(BaseAdapter):
+
+    NAME = "Kimi Code"
+    BINARY = "kimi"
+    CONFIG_DIR = "~/.kimi"
+    PROJECT_DIR = "KIMI.md"
+    PROCESS_NAME = None
+    INSTRUCTION_FILE = "KIMI.md"
+
+    def install(self) -> None:
+        self._write_instruction_file(
+            self.project_root / "KIMI.md",
+            self._instruction_content(),
+        )
+        self._inject_mcp_config(
+            Path.home() / ".kimi" / "mcp.json"
+        )
+
+    def is_detected(self) -> bool:
+        return (
+            self._detect_binary()
+            or self._detect_config_dir()
+            or self._detect_project_dir()
+        )