FatinShadab · Jun 1, 2026 · May 28, 2026 · May 28, 2026 · May 28, 2026 · May 28, 2026
diff --git a/.cursor/rules/watcher-knowledge-graph.mdc b/.cursor/rules/watcher-knowledge-graph.mdc
@@ -0,0 +1,29 @@
+---
+description: CodeGenome knowledge graph and MCP Context
+alwaysApply: true
+---
+
+# CodeGenome MCP Integration
+
+You are operating within a repository analyzed by CodeGenome, an architectural knowledge graph tool. This project contains a `.genome/` directory.
+
+## Core Directives
+
+1. **Mandatory MCP Usage**: When `.genome/watcher.db` exists, you MUST use CodeGenome MCP access for all codebase, architecture, dependency, or symbol queries whenever it is available.
+2. **Access Order**: First use native CodeGenome MCP tools exposed in your context. If those tools are missing, you MAY try a local MCP HTTP endpoint such as `http://127.0.0.1:7331/mcp` when the user has started it or configured it. Treat this as MCP transport access, not as an arbitrary application HTTP API.
+3. **Prefer Graph over Grep**: Use graph-backed MCP tools instead of raw file searching (`grep`) or reading entire files blindly. The graph provides semantic understanding.
+4. **Fallback Gracefully**: If native MCP tools are missing and HTTP MCP access is unavailable, incompatible, or returns empty data, tell the user exactly what failed and what to configure. Then, if needed, read `.genome/graph.json` or `.genome/exports/*.md` before resorting to standard text searches.
+5. **Keep Context Fresh**: After modifying code files, remind the user to run `codegenome analyze` or start the live evolution server `codegenome evolve --live` to keep the graph updated.
+
+## Available MCP Capabilities
+
+- **Discovery**: `search_nodes` (find symbols)
+- **Relationships**: `get_neighbors` (imports, callers, callees)
+- **Architecture**: `get_entry_points`, `get_dead_code`, `get_circular_deps`, `get_god_nodes`
+- **Metrics**: `get_complexity`, `get_churn`, `get_graph` (summary statistics)
+- **Evolution**: `get_timeline`, `get_changes` (architectural diffs)
+
+## Constraints & Behaviors
+
+- Only read `.genome/graph.json` or `.genome/exports/*.md` directly if native MCP tools and local HTTP MCP transport are unavailable or fail to surface enough context.
+- Verify your MCP usage by monitoring tool call success. If native tools are missing, try the configured local HTTP MCP endpoint when possible. If both native and HTTP MCP access fail, politely ask the user to configure their editor's MCP settings to run `codegenome mcp-start` (stdio) or start the server with `codegenome mcp-start --transport http`.
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -0,0 +1,24 @@
+# CodeGenome Knowledge Graph (MCP)
+
+You are operating within a repository analyzed by CodeGenome, an architectural knowledge graph tool. This project contains a `.genome/` directory.
+
+## Core Directives
+
+1. **Mandatory MCP Usage**: When `.genome/watcher.db` exists, you MUST use CodeGenome MCP access for all codebase, architecture, dependency, or symbol queries whenever it is available.
+2. **Access Order**: First use native CodeGenome MCP tools exposed in your context. If those tools are missing, you MAY try a local MCP HTTP endpoint such as `http://127.0.0.1:7331/mcp` when the user has started it or configured it. Treat this as MCP transport access, not as an arbitrary application HTTP API.
+3. **Prefer Graph over Grep**: Use graph-backed MCP tools instead of raw file searching (`grep`) or reading entire files blindly. The graph provides semantic understanding.
+4. **Fallback Gracefully**: If native MCP tools are missing and HTTP MCP access is unavailable, incompatible, or returns empty data, tell the user exactly what failed and what to configure. Then, if needed, read `.genome/graph.json` or `.genome/exports/*.md` before resorting to standard text searches.
+5. **Keep Context Fresh**: After modifying code files, remind the user to run `codegenome analyze` or start the live evolution server `codegenome evolve --live` to keep the graph updated.
+
+## Available MCP Capabilities
+
+- **Discovery**: `search_nodes` (find symbols)
+- **Relationships**: `get_neighbors` (imports, callers, callees)
+- **Architecture**: `get_entry_points`, `get_dead_code`, `get_circular_deps`, `get_god_nodes`
+- **Metrics**: `get_complexity`, `get_churn`, `get_graph` (summary statistics)
+- **Evolution**: `get_timeline`, `get_changes` (architectural diffs)
+
+## Constraints & Behaviors
+
+- Only read `.genome/graph.json` or `.genome/exports/*.md` directly if native MCP tools and local HTTP MCP transport are unavailable or fail to surface enough context.
+- Verify your MCP usage by monitoring tool call success. If native tools are missing, try the configured local HTTP MCP endpoint when possible. If both native and HTTP MCP access fail, politely ask the user to configure their editor's MCP settings to run `codegenome mcp-start` (stdio) or start the server with `codegenome mcp-start --transport http`.
diff --git a/.github/workflows/compatibility.yml b/.github/workflows/compatibility.yml
@@ -0,0 +1,41 @@
+name: Compatibility
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+jobs:
+  install-and-parser-smoke:
+    name: "${{ matrix.os }} / py${{ matrix.python-version }}"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-14]
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Upgrade build tooling
+        run: python -m pip install --upgrade pip setuptools wheel
+
+      - name: Install package and test dependencies
+        run: |
+          python -m pip install .
+          python -m pip install pytest
+
+      - name: Parser test suite
+        run: python -m pytest tests/test_parser.py -q
+
+      - name: CLI smoke test
+        run: |
+          codegenome --help
+          python -c "import codegenome; print(codegenome.__version__)"
diff --git a/.gitignore b/.gitignore
@@ -22,3 +22,5 @@ Thumbs.db
 .env
 .env.*
 *.log
+
+*.tex
diff --git a/.idea/.gitignore b/.idea/.gitignore
diff --git a/.idea/codegenome.iml b/.idea/codegenome.iml
diff --git a/.idea/compiler.xml b/.idea/compiler.xml
diff --git a/.idea/misc.xml b/.idea/misc.xml
diff --git a/.idea/modules.xml b/.idea/modules.xml
diff --git a/.idea/vcs.xml b/.idea/vcs.xml
diff --git a/.windsurfrules b/.windsurfrules
@@ -0,0 +1,24 @@
+# CodeGenome Knowledge Graph (MCP)
+
+You are operating within a repository analyzed by CodeGenome, an architectural knowledge graph tool. This project contains a `.genome/` directory.
+
+## Core Directives
+
+1. **Mandatory MCP Usage**: When `.genome/watcher.db` exists, you MUST use CodeGenome MCP access for all codebase, architecture, dependency, or symbol queries whenever it is available.
+2. **Access Order**: First use native CodeGenome MCP tools exposed in your context. If those tools are missing, you MAY try a local MCP HTTP endpoint such as `http://127.0.0.1:7331/mcp` when the user has started it or configured it. Treat this as MCP transport access, not as an arbitrary application HTTP API.
+3. **Prefer Graph over Grep**: Use graph-backed MCP tools instead of raw file searching (`grep`) or reading entire files blindly. The graph provides semantic understanding.
+4. **Fallback Gracefully**: If native MCP tools are missing and HTTP MCP access is unavailable, incompatible, or returns empty data, tell the user exactly what failed and what to configure. Then, if needed, read `.genome/graph.json` or `.genome/exports/*.md` before resorting to standard text searches.
+5. **Keep Context Fresh**: After modifying code files, remind the user to run `codegenome analyze` or start the live evolution server `codegenome evolve --live` to keep the graph updated.
+
+## Available MCP Capabilities
+
+- **Discovery**: `search_nodes` (find symbols)
+- **Relationships**: `get_neighbors` (imports, callers, callees)
+- **Architecture**: `get_entry_points`, `get_dead_code`, `get_circular_deps`, `get_god_nodes`
+- **Metrics**: `get_complexity`, `get_churn`, `get_graph` (summary statistics)
+- **Evolution**: `get_timeline`, `get_changes` (architectural diffs)
+
+## Constraints & Behaviors
+
+- Only read `.genome/graph.json` or `.genome/exports/*.md` directly if native MCP tools and local HTTP MCP transport are unavailable or fail to surface enough context.
+- Verify your MCP usage by monitoring tool call success. If native tools are missing, try the configured local HTTP MCP endpoint when possible. If both native and HTTP MCP access fail, politely ask the user to configure their editor's MCP settings to run `codegenome mcp-start` (stdio) or start the server with `codegenome mcp-start --transport http`.
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,24 @@
+# CodeGenome Knowledge Graph (MCP)
+
+You are operating within a repository analyzed by CodeGenome, an architectural knowledge graph tool. This project contains a `.genome/` directory.
+
+## Core Directives
+
+1. **Mandatory MCP Usage**: When `.genome/watcher.db` exists, you MUST use CodeGenome MCP access for all codebase, architecture, dependency, or symbol queries whenever it is available.
+2. **Access Order**: First use native CodeGenome MCP tools exposed in your context. If those tools are missing, you MAY try a local MCP HTTP endpoint such as `http://127.0.0.1:7331/mcp` when the user has started it or configured it. Treat this as MCP transport access, not as an arbitrary application HTTP API.
+3. **Prefer Graph over Grep**: Use graph-backed MCP tools instead of raw file searching (`grep`) or reading entire files blindly. The graph provides semantic understanding.
+4. **Fallback Gracefully**: If native MCP tools are missing and HTTP MCP access is unavailable, incompatible, or returns empty data, tell the user exactly what failed and what to configure. Then, if needed, read `.genome/graph.json` or `.genome/exports/*.md` before resorting to standard text searches.
+5. **Keep Context Fresh**: After modifying code files, remind the user to run `codegenome analyze` or start the live evolution server `codegenome evolve --live` to keep the graph updated.
+
+## Available MCP Capabilities
+
+- **Discovery**: `search_nodes` (find symbols)
+- **Relationships**: `get_neighbors` (imports, callers, callees)
+- **Architecture**: `get_entry_points`, `get_dead_code`, `get_circular_deps`, `get_god_nodes`
+- **Metrics**: `get_complexity`, `get_churn`, `get_graph` (summary statistics)
+- **Evolution**: `get_timeline`, `get_changes` (architectural diffs)
+
+## Constraints & Behaviors
+
+- Only read `.genome/graph.json` or `.genome/exports/*.md` directly if native MCP tools and local HTTP MCP transport are unavailable or fail to surface enough context.
+- Verify your MCP usage by monitoring tool call success. If native tools are missing, try the configured local HTTP MCP endpoint when possible. If both native and HTTP MCP access fail, politely ask the user to configure their editor's MCP settings to run `codegenome mcp-start` (stdio) or start the server with `codegenome mcp-start --transport http`.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to Codegenome are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.4] - 2026-06-01
+
+### Added
+
+- **Copyable TUI console outputs** — users can now select text in the log panes and press `Ctrl+C` to copy it to the clipboard.
+- **LAN live graph sharing** — `codegenome evolve --live --lan` binds HTTP and WebSocket to `0.0.0.0` so other devices on the same network can open the live graph. The CLI prints a shareable LAN URL (for example `http://192.168.1.42:8000/graph.html?live=1`).
+- **TUI MCP HTTP mode controls** — the dashboard now includes separate **Start MCP HTTP (Local)** and **Start MCP HTTP (LAN)** buttons so users can intentionally choose localhost-only or LAN exposure.
+- **Git-aware file filtering** — the scanner respects workspace `.gitignore` and `.genomeignore` files, including nested ignore files in subdirectories, negation rules (`!pattern`), and anchored patterns.
+- **TUI workspace info page** — after setting a workspace, the TUI shows tracked folders, file extensions, and discovered `.gitignore` files before you run analyze or evolve.
+- **TUI live-evolve controls** — buttons for **Live Evolve (Local)**, **Live Evolve (LAN)**, and **Quit** to start or stop background processes from the dashboard.
+- **Live graph AI chat** — the HTML graph UI includes an in-browser chat panel backed by OpenAI, Google Gemini, Groq, Ollama (local), and Ollama Cloud. API keys are stored under `.genome/ai-chat.json` and never echoed back to the browser.
+- **Graph context profiles for AI chat** — selectable context sizes (`minimal`, `small`, `medium`, `full`, `max`) control how much neighborhood data is sent with each prompt.
+- **MCP `query_graph` tool** — filter graph nodes by type, file path prefix, or symbol kind.
+- **`codegenome mcp-start --transport` and `--port`** — start the MCP server over stdio (default) or HTTP from the modern CLI and TUI.
+- **`pathspec` dependency** — powers gitignore-compatible pattern matching.
+
+### Changed
+
+- Default ignore list always excludes `.git/`, `.venv/`, `node_modules/`, `__pycache__/`, `*.pyc`, `.genome/`, and `.genomeignore` in addition to workspace ignore files.
+- MCP server refreshes the latest timeline snapshot before tool reads so agents always see current graph data after `analyze` or live evolve.
+- `codegenome mcp-start` adds `--lan` for intentional HTTP LAN binding from CLI/TUI workflows.
+- Agent instruction templates (`codegenome rules`) now direct agents to use native MCP tools instead of raw HTTP/curl calls.
+
+### Fixed
+
+- MCP tool handlers return richer graph intelligence data (dead code, entry points, complexity, churn) with improved filtering for generated assets and public API symbols.
+- Agent rules no longer reference misleading HTTP endpoints that caused agents to `curl` the server instead of using MCP transport.
+- MCP server keeps localhost-only behavior by default and now requires an explicit remote HTTP opt-in (`--allow-remote-http`) for non-loopback hosts.
+- Release lint blockers (unused imports and test lint violations) were resolved so full lint/test/build gates pass before upload.
+- Tree-sitter dependency constraints now support Python 3.12+ installations (including macOS Apple Silicon) while preserving legacy pins for Python 3.11 compatibility (fixes [#1](https://github.com/Ogro-Projukti/codegenome/issues/1)).
+- Updated tree-sitter `Parser` initialization to support both legacy and modern (`>=0.23`) API signatures without breaking runtime.
+
+### Documentation
+
+- CLI reference covers `--lan`, TUI live modes, ignore-rule behavior, and MCP transport options.
+- README quick start includes the LAN evolve example.
+- Release notes and upgrade instructions in `docs/release-0.1.4.md`.
+
+[0.1.4]: https://github.com/Ogro-Projukti/codegenome/releases/tag/v0.1.4
diff --git a/CITATION.cff b/CITATION.cff
@@ -0,0 +1,39 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: "Turja"
+    given-names: "Md. Fatin Shadab"
+    orcid: "https://orcid.org/0009-0008-0026-2947"
+    affiliation: "United International University"
+title: "CodeGenome"
+version: "0.1.4"
+date-released: "2026-05-30"
+license: "MIT"
+repository-code: "https://github.com/Ogro-Projukti/codegenome"
+url: "https://codegenome.pages.dev/"
+abstract: >-
+  CodeGenome is an open-source codebase analyzer that treats software architecture
+  as a connectome—a map of connections between functions, classes, files, and imports.
+  It builds a project-level dependency graph, provides a higher-level community view
+  using Leiden community detection, and features real-time updates via a filesystem observer.
+  An integrated Model Context Protocol (MCP) server lets AI agents query structural
+  architectural context directly instead of consuming raw source files.
+keywords:
+  - "software-architecture"
+  - "code-analysis"
+  - "dependency-graphs"
+  - "community-detection"
+  - "model-context-protocol"
+  - "ai-assisted-development"
+preferred-citation:
+  type: generic
+  authors:
+    - family-names: "Turja"
+      given-names: "Md. Fatin Shadab"
+      orcid: "https://orcid.org/0009-0008-0026-2947"
+      affiliation: "United International University"
+  title: "CodeGenome: A Real-Time Hierarchical Codebase Connectome Engine for AI-Assisted Development"
+  year: 2026
+  medium: "Technical Report"
+  publisher: "Ogro-Projukti"
+  url: "https://github.com/Ogro-Projukti/codegenome"
-Original file line number
+Diff line change
@@ Expand Up / @@ -22,3 +22,5 @@ Thumbs.db @@
     .env
     .env.*
     *.log
+    *.tex