cntx-ui/README.md

Autonomous Repository Intelligence engine with web UI and MCP server. Unified semantic code understanding, local RAG, and agent working memory.

# cntx-ui

Semantic code analysis and context management for AI agents. Turns a codebase into searchable, structured context that agents can navigate efficiently.

## What it does

- **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

## Install

```bash
npm install -g cntx-ui
```

## Usage

```bash
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.

## Agent interface

Agents interact through MCP tools or the HTTP API:

| MCP Tool | What it does |
| :--- | :--- |
| `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 |
| `artifacts/list` | List normalized project artifacts (OpenAPI + Navigation) |
| `artifacts/get_openapi` | Return OpenAPI artifact summary and payload |
| `artifacts/get_navigation` | Return Navigation artifact summary and payload |
| `artifacts/summarize` | Compact cross-artifact summary for agents |
| `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`.

Artifact HTTP endpoints:
- `GET /api/artifacts`
- `GET /api/artifacts/openapi`
- `GET /api/artifacts/navigation`

## How it works

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

- 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

## License

MIT