https://github.com/whaleen/cntx-ui
File context management tool with web UI and MCP server for AI development workflows - bundle project files for LLM consumption
https://github.com/whaleen/cntx-ui
ai ai-development ai-workflow bundling claude-desktop cli-tool codebase codebase-bundling context-management development-tools file-aggregation file-bundling file-management llm-tools mcp-server model-context-protocol project-context react websocket
Last synced: 14 days ago
JSON representation
File context management tool with web UI and MCP server for AI development workflows - bundle project files for LLM consumption
- Host: GitHub
- URL: https://github.com/whaleen/cntx-ui
- Owner: whaleen
- Created: 2025-05-22T00:37:30.000Z (10 months ago)
- Default Branch: master
- Last Pushed: 2026-02-28T09:54:59.000Z (27 days ago)
- Last Synced: 2026-02-28T10:17:12.755Z (27 days ago)
- Topics: ai, ai-development, ai-workflow, bundling, claude-desktop, cli-tool, codebase, codebase-bundling, context-management, development-tools, file-aggregation, file-bundling, file-management, llm-tools, mcp-server, model-context-protocol, project-context, react, websocket
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/cntx-ui
- Size: 33.2 MB
- Stars: 0
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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 # 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