cntx-ui 2.0.13 → 3.0.0

package/README.md

@@ -1,371 +1,83 @@
 # cntx-ui
 
-Minimal file bundling and tagging tool for AI development with web interface.
+**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.
 
-## Features
+## 🚀 Key Capabilities
 
-- File bundling and organization for AI development workflows
-- Web-based UI for managing bundles and configurations
-- **Model Context Protocol (MCP) server** for AI integration
-- Hidden files management
-- Cursor rules integration
-- WebSocket-based real-time updates
-- CLI tools for automation
+### 🧠 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.
 
-## Installation
+### 🔍 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.
 
-### Global Installation (Recommended)
+### 🤖 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 Installation
-
+### Local Development
 ```bash
 git clone https://github.com/nothingdao/cntx-ui.git
 cd cntx-ui
 npm install
+cd web && npm install
 ```
 
-## Usage
+---
 
-### Initialize a Project
+## 📖 Usage
 
+### Initialize a Project
 ```bash
-# Initialize cntx-ui in your project
 cntx-ui init
-
-# Start the web interface
 cntx-ui watch
-
-# Visit http://localhost:3333 to access the web UI
 ```
+*Visit `http://localhost:3333` to access the Visual Dashboard.*
 
 ### CLI Commands
+| Command | Description |
+| :--- | :--- |
+| `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. |
 
-```bash
-# Generate bundles
-cntx-ui bundle <name>
-
-# Check project status
-cntx-ui status
-
-# Start web server on custom port
-cntx-ui watch [port]
-
-# Start web server with MCP status tracking
-cntx-ui watch --with-mcp
-
-# Start MCP server for AI integration
-cntx-ui mcp
-
-# Add project to Claude Desktop MCP configuration
-cntx-ui setup-mcp
-```
-
-### MCP Integration
-
-cntx-ui can function as an MCP (Model Context Protocol) server, providing AI tools with direct access to your project bundles:
-
-```bash
-# Start MCP server
-cntx-ui mcp
-```
-
-**Available MCP Resources:**
-- `cntx://bundle/<name>` - Access any bundle as XML content
-- `cntx://file/<path>` - Access individual project files
-
-**Available MCP Tools:**
-- `list_bundles` - List all available bundles
-- `get_bundle` - Retrieve specific bundle content  
-- `generate_bundle` - Regenerate a bundle
-- `get_file_tree` - Get project file structure
-- `get_project_status` - Get current project status
-
-## Development
+---
 
-### Prerequisites
+## 🏗 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)
 
-- Node.js >= 18.0.0
-- npm
+---
 
-### Setup Development Environment
-
-1. **Clone and install dependencies:**
-   ```bash
-   git clone https://github.com/nothingdao/cntx-ui.git
-   cd cntx-ui
-   npm install
-   ```
-
-2. **Install web dependencies:**
-   ```bash
-   cd web
-   npm install
-   cd ..
-   ```
-
-### Development Workflow
-
-#### Running in Development Mode
-
-1. **Start the backend server:**
-   ```bash
-   npm run dev
-   ```
-
-2. **Start the frontend development server:**
-   ```bash
-   npm run dev:web
-   ```
-   
-   The web interface will be available at `http://localhost:5173` (Vite dev server)
-
-#### Building the Project
-
-1. **Build web interface only:**
-   ```bash
-   npm run build:web
-   ```
-
-2. **Build entire project:**
-   ```bash
-   npm run build
-   ```
-
-3. **Automated build with validation:**
-   ```bash
-   ./build.sh
-   ```
-
-### Project Structure
-
-```
-cntx-ui/
-├── bin/                    # CLI executable
-├── web/                    # React frontend
-│   ├── src/
-│   │   ├── components/     # React components
-│   │   ├── hooks/          # Custom hooks
-│   │   ├── utils/          # Utility functions
-│   │   └── lib/            # Libraries and configurations
-│   ├── dist/               # Built frontend (generated)
-│   └── package.json        # Frontend dependencies
-├── server.js               # WebSocket server
-├── package.json            # Main package configuration
-├── build.sh                # Build automation script
-└── test-local.sh           # Local testing script
-```
-
-### Available Scripts
-
-| Script | Description |
-|--------|-------------|
-| `npm run dev` | Start backend server |
-| `npm run dev:web` | Start frontend dev server |
-| `npm run build` | Build entire project |
-| `npm run build:web` | Build frontend only |
-| `npm test:local` | Install and test package locally |
-
-## MCP Server Setup
-
-### Quick Setup with setup-mcp Command
-
-The easiest way to configure cntx-ui for Claude Desktop:
-
-```bash
-# Navigate to your project directory
-cd /path/to/your/project
-
-# Initialize cntx-ui if not already done
-cntx-ui init
-
-# Add this project to Claude Desktop MCP configuration
-cntx-ui setup-mcp
-```
+## 🗺 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.
 
-This automatically adds your project to Claude Desktop's configuration file and allows you to work with multiple projects simultaneously.
-
-### Claude Desktop Integration
-
-#### Multi-Project Setup (Recommended)
-
-You can use cntx-ui across multiple projects by running `setup-mcp` in each project directory:
-
-```bash
-# Project 1
-cd /Users/you/project1
-cntx-ui setup-mcp
-
-# Project 2  
-cd /Users/you/project2
-cntx-ui setup-mcp
-```
-
-This creates entries in your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "cntx-ui-project1": {
-      "command": "sh",
-      "args": ["-c", "cd /Users/you/project1 && node /path/to/cntx-ui/bin/cntx-ui.js mcp"],
-      "cwd": "/Users/you/project1"
-    },
-    "cntx-ui-project2": {
-      "command": "sh", 
-      "args": ["-c", "cd /Users/you/project2 && node /path/to/cntx-ui/bin/cntx-ui.js mcp"],
-      "cwd": "/Users/you/project2"
-    }
-  }
-}
-```
-
-#### Manual Configuration
-
-For manual setup, add to your Claude Desktop configuration:
-
-```json
-{
-  "mcpServers": {
-    "cntx-ui-projectname": {
-      "command": "sh",
-      "args": ["-c", "cd /path/to/your/project && cntx-ui mcp"],
-      "cwd": "/path/to/your/project"
-    }
-  }
-}
-```
-
-### Other MCP Clients
-
-For other MCP-compatible clients, use:
-- **Command**: `cntx-ui mcp`
-- **Transport**: stdio
-- **Working Directory**: Your project root
-
-### MCP Workflow
-
-1. **Setup**: Run `cntx-ui setup-mcp` in each project you want to use with Claude Desktop
-2. **Visual Configuration**: Use `cntx-ui watch` to configure bundles via web UI
-3. **AI Integration**: AI clients connect via MCP to access bundles across all configured projects
-4. **Real-time Updates**: Changes in web UI immediately available to AI tools
-5. **Multi-Project**: Claude Desktop can access bundles from all configured projects simultaneously
-
-## Testing
-
-### Local Testing
-
-1. **Run automated test suite:**
-   ```bash
-   ./test-local.sh
-   ```
-
-2. **Manual testing:**
-   ```bash
-   # Build and pack
-   npm run build
-   npm pack
-   
-   # Install globally for testing
-   npm install -g ./cntx-ui-*.tgz
-   
-   # Test in a new project
-   mkdir test-project && cd test-project
-   cntx-ui init
-   cntx-ui watch
-   ```
-
-### Test Coverage
-
-The test suite covers:
-- Project initialization
-- Bundle generation
-- Web server functionality
-- API endpoints
-- File management operations
-
-## Publishing
-
-### Prerequisites for Publishing
-
-- npm account with publish permissions
-- Clean git working directory
-- All tests passing
-
-### Publishing Steps
-
-1. **Update version:**
-   ```bash
-   npm version patch  # or minor/major
-   ```
-
-2. **Build and validate:**
-   ```bash
-   ./build.sh
-   ```
-
-3. **Test locally:**
-   ```bash
-   ./test-local.sh
-   ```
-
-4. **Publish to npm:**
-   ```bash
-   # Stable release
-   npm publish
-   
-   # Beta release
-   npm publish --tag beta
-   ```
-
-### Automated Publishing Workflow
-
-Use the build script for a complete workflow:
-
-```bash
-./build.sh
-# Follow prompts for local testing
-# If tests pass, run: npm publish
-```
-
-## Configuration
-
-### Environment Variables
-
-- `PORT` - Override default server port (default: 3333)
-- `NODE_ENV` - Set environment (development/production)
-
-### Project Configuration
-
-cntx-ui creates these files in your project:
-- `.cntx/config.json` - Main configuration
-- `.cntxignore` - Files to ignore
-- `.cursorrules` - Cursor editor rules
-
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch
-3. Make changes following the existing code style
-4. Run tests: `./test-local.sh`
-5. Submit a pull request
-
-## Technology Stack
-
-- **Backend:** Node.js, WebSocket (ws)
-- **Frontend:** React 19, TypeScript, Vite
-- **UI:** Tailwind CSS, Radix UI
-- **State Management:** TanStack Query
-- **Build Tools:** Vite, TypeScript compiler
-
-## License
+See [VISION.md](./VISION.md) for the full roadmap.
 
+## 📄 License
 MIT
-
-## Support
-
-- GitHub Issues: [Report bugs or request features](https://github.com/nothingdao/cntx-ui/issues)
-- Documentation: Check the web interface for detailed usage guides

package/VISION.md

@@ -0,0 +1,110 @@
+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.

package/bin/cntx-ui-mcp.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+# Wrapper script to run cntx-ui MCP server in current directory
+cd "$(pwd)" && npx cntx-ui mcp