cntx-ui 3.0.0 → 3.0.1

package/README.md

@@ -1,83 +1,67 @@
 # cntx-ui
 
-**cntx-ui** is the interface layer between human mental models and machine understanding of codebases. It transforms raw source code into a traversable knowledge graph for AI agents, providing surgical context management, semantic discovery, and real-time synchronization.
+Semantic code analysis and context management for AI agents. Turns a codebase into searchable, structured context that agents can navigate efficiently.
 
-## 🚀 Key Capabilities
+## What it does
 
-### 🧠 Semantic Code Understanding
-Unlike simple file bundlers, `cntx-ui` performs function-level analysis of your codebase:
-- **Semantic Splitting:** Automatically extracts functions, types, and interfaces with their relevant context (imports/dependencies).
-- **Heuristic Categorization:** Classifies code by purpose (e.g., API Handlers, React Hooks, UI Components) using a configurable heuristics engine.
-- **Complexity Metrics:** Identifies hotspots and architectural patterns automatically.
+- **Semantic analysis** — parses your code at the function level using tree-sitter, extracts purpose, complexity, and relationships
+- **Local vector search** — embeds code chunks locally (all-MiniLM-L6-v2 via Transformers.js) for semantic similarity search with no external API calls
+- **Bundle system** — group files into logical bundles (by feature, layer, or pattern) for structured context delivery
+- **MCP server** — exposes 28+ tools to Claude Code, Claude Desktop, or any MCP-compatible client
+- **Web dashboard** — visual interface at localhost:3333 for managing bundles, browsing semantic analysis, and editing agent rules
+- **Real-time sync** — watches for file changes and keeps analysis, bundles, and embeddings current
 
-### 🔍 Local Vector Search
-Integrated RAG (Retrieval-Augmented Generation) without external dependencies:
-- **Local Embeddings:** Powered by `Transformers.js` using the `all-MiniLM-L6-v2` model.
-- **In-Memory Vector Store:** Perform semantic similarity searches across your codebase to find related implementations instantly.
+## Install
 
-### 🤖 AI Agent Runtime
-A specialized runtime that exposes advanced behavior modes via MCP:
-- **Discovery Mode:** Generates comprehensive architectural overviews.
-- **Query Mode:** Answers specific questions using semantic search and AST analysis.
-- **Investigation Mode:** Analyzes existing implementations to suggest integration points for new features.
-- **Organizer Mode:** Audits and optimizes project organization and bundle health.
-
-### 📦 Smart Bundling & MCP
-- **Dynamic Bundles:** Group files by human intent or machine discovery.
-- **MCP Server:** Expose bundles, files, and agent tools directly to Claude Desktop or any MCP-compatible client.
-- **Real-time Sync:** WebSocket-based updates ensure your AI context is always fresh.
-
----
-
-## 🛠 Installation
-
-### Global Installation (Recommended)
 ```bash
 npm install -g cntx-ui
 ```
 
-### Local Development
+## Usage
+
 ```bash
-git clone https://github.com/nothingdao/cntx-ui.git
-cd cntx-ui
-npm install
-cd web && npm install
+cntx-ui init          # scaffold .cntx directory, generate .mcp.json
+cntx-ui watch         # start web server on port 3333
+cntx-ui mcp           # start MCP server on stdio
+cntx-ui bundle <name> # regenerate a specific bundle
+cntx-ui status        # show project health and bundle state
+cntx-ui setup-mcp     # configure Claude Desktop integration
 ```
 
----
+After `cntx-ui init`, agents discover tools automatically via `.mcp.json`. The `.cntx/AGENT.md` file provides an onboarding handshake with tool reference and project overview.
 
-## 📖 Usage
+## Agent interface
 
-### Initialize a Project
-```bash
-cntx-ui init
-cntx-ui watch
-```
-*Visit `http://localhost:3333` to access the Visual Dashboard.*
+Agents interact through MCP tools or the HTTP API:
 
-### CLI Commands
-| Command | Description |
+| MCP Tool | What it does |
 | :--- | :--- |
-| `cntx-ui status` | View project health and bundle coverage. |
-| `cntx-ui bundle <name>` | Manually trigger a bundle generation. |
-| `cntx-ui setup-mcp` | Automatically configure Claude Desktop integration. |
-| `cntx-ui mcp` | Start the MCP server on stdio. |
+| `agent/discover` | Architectural overview of the codebase |
+| `agent/query` | Semantic search — "where is auth handled?" |
+| `agent/investigate` | Find integration points for a new feature |
+| `agent/organize` | Audit and optimize bundle structure |
+| `list_bundles` | List all bundles with metadata |
+| `get_bundle` | Get full bundle content as XML |
+| `get_semantic_chunks` | Get all analyzed code chunks |
+| `read_file` / `write_file` | File operations with bundle context |
+
+Full tool reference with parameters is generated in `.cntx/AGENT.md` and `.cntx/TOOLS.md`.
 
----
+## How it works
 
-## 🏗 Technology Stack
-- **Backend:** Node.js, `better-sqlite3`, `ws`
-- **AI/ML:** `Transformers.js` (Local Embeddings), `chromadb` (Vector Store)
-- **Parsing:** `tree-sitter`, Custom Semantic Splitter
-- **Frontend:** React 19, TypeScript, Vite, Tailwind CSS, Radix UI, Lucide
-- **Protocol:** Model Context Protocol (MCP)
+1. **tree-sitter** parses source files into AST, extracts functions/types/interfaces
+2. **Heuristics engine** classifies each chunk by purpose, business domain, and technical patterns based on file paths, imports, and naming conventions
+3. **Embeddings** are generated locally and stored in SQLite for persistent vector search
+4. **Bundles** group files by glob patterns — auto-suggested on init based on project structure
+5. **MCP server** and **HTTP API** expose everything to agents with consistent response shapes
 
----
+## Tech stack
 
-## 🗺 Vision
-We are building more than a tool; we are building **Repository Intelligence**. Our goal is to create a self-documenting, AI-optimized environment where the friction between "knowing" a codebase and "modifying" it vanishes.
+- Node.js, better-sqlite3, ws (WebSocket)
+- tree-sitter (AST parsing), Transformers.js (local embeddings)
+- React 19, TypeScript, Vite, Tailwind CSS (web dashboard)
+- Model Context Protocol (MCP) via JSON-RPC 2.0
 
-See [VISION.md](./VISION.md) for the full roadmap.
+## License
 
-## 📄 License
 MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cntx-ui",
   "type": "module",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Autonomous Repository Intelligence engine with web UI and MCP server. Unified semantic code understanding, local RAG, and agent working memory.",
   "keywords": [
     "repository-intelligence",

package/VISION.md

@@ -1,110 +0,0 @@
-We're building the interface layer between human mental models and machine understanding of codebases.
-
-## The Complete Knowledge Graph
-
-What we're really creating is a traversable knowledge graph for AI agents:
-
-```
-// The full context system an AI agent can navigate:
-{
-  project: {
-    fileTree: rawFileStructure,           // Raw filesystem
-    bundles: humanDefinedCollections,     // Explicit human organization
-    chunks: aiDiscoveredPatterns,         // Machine-learned semantic groups
-    aiRules: contextualInstructions,      // How to work with this code
-    metadata: projectUnderstanding        // What this codebase "does"
-  }
-}
-```
-
-## Multi-Layer Understanding System
-
-Layer 1: Raw Structure (File Tree)
-
-- Physical organization
-- What files exist, where they are
-
-Layer 2: Human Intent (Bundles)
-
-- "These files should be considered together"
-- Explicit human curation for specific purposes
-
-Layer 3: Machine Discovery (Semantic Chunks)
-
-- "These files naturally cluster together"
-- AI-discovered relationships and patterns
-
-Layer 4: Working Instructions (AI Rules + Context)
-
-- "When working on X, consider Y"
-- How to navigate and modify the code effectively
-
-## The Human ↔ Machine Interface
-
-This becomes a bidirectional translation layer:
-
-Human → Machine:
-
-- "I'm working on authentication" → AI gets auth chunks + related bundles +
-  security rules
-- "This is an e-commerce app" → AI understands domain context for better
-  suggestions
-- "These files are related" → Creates explicit bundle relationships
-
-Machine → Human:
-
-- AI discovers "payment processing is tightly coupled across 12 files"
-- AI suggests "these utility functions could be shared between features"
-- AI provides "here's what your codebase is primarily about" overview
-
-Ongoing Repository Intelligence
-
-As the tool runs continuously, it builds living documentation:
-
-```
-// Repository understanding that evolves:
-{
-  codebasePersonality: {
-    primaryPurpose: "E-commerce platform with React frontend",
-    architecturalPatterns: ["feature-based organization", "custom hooks
-pattern"],
-    complexityHotspots: ["payment processing", "user authentication"],
-    evolutionTrends: ["moving from REST to GraphQL", "adding TypeScript
-gradually"]
-  },
-
-  workingMemory: {
-    recentChanges: "Auth system refactored last week",
-    emergingPatterns: "New utilities being created for form handling",
-    maintenanceNeeds: "Several components showing high complexity"
-  }
-}
-```
-
-## The "What Is This Codebase About?" Dashboard
-
-Users get a high-level strategic view:
-
-- Semantic Map: Visual representation of chunks and relationships
-- Complexity Overview: Where the hard problems live
-- Evolution Tracking: How the code is changing over time
-- AI Recommendations: Suggested improvements and organizational changes
-- Context Preparation: Pre-built knowledge packages for different types of AI
-  assistance
-
-This creates a self-documenting, AI-optimized codebase where both humans and
-machines can quickly understand:
-
-1. What this code does
-2. How it's organized
-3. Where to make changes
-4. How different parts relate
-5. What context an AI agent needs to help effectively
-
-The tool becomes the source of truth for codebase understanding, continuously
-learning and improving its model of the project while giving humans control
-over the organizational principles.
-
-This is exactly the kind of human-AI collaboration interface that will become
-essential as codebases get more complex and AI assistance becomes more
-sophisticated.