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