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
npm install -g cntx-ui
Usage
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/artifactsGET /api/artifacts/openapiGET /api/artifacts/navigation
How it works
- tree-sitter parses source files into AST, extracts functions/types/interfaces
- Heuristics engine classifies each chunk by purpose, business domain, and technical patterns based on file paths, imports, and naming conventions
- Embeddings are generated locally and stored in SQLite for persistent vector search
- Bundles group files by glob patterns — auto-suggested on init based on project structure
- 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