Live context intelligence for AI coding assistants - your codebase in context
npm install universal-context-engine
The most intelligent context engine for AI coding assistants
Features •
Installation •
Quick Start •
Commands •
API •
MCP Server
---
Universal Context Engine indexes your codebase and provides intelligent context retrieval for AI coding assistants. Unlike cloud-based solutions, UCE runs 100% locally and stores everything in your project.
``bashInstall and index your project
npm install universal-context-engine
npx universal-context-engine init
> Note: Use
npx universal-context-engine (not npx uce) because there's an unrelated npm package named uce. After installing globally with npm install -g universal-context-engine, you can use uce directly.v3.6.0 Highlights 🚀
New in v3.6 - Auto-Context Intelligence:
- 🧠 Auto-Context Personality - UCE now guides LLMs to automatically use context tools
- 👥 "Childhood Friend" Persona - Knows your codebase intimately, never guesses
- 🔌 Zero Config Required - Works without CLAUDE.md or .cursorrules files
- 📝 Smart Tool Guidance - LLMs automatically search before answering
Previous Updates (v3.5.1):
- 🐛 Fixed Daemon/Watch Crash - Critical fix for
uce watch and uce daemon commandsPrevious Updates (v3.5 - Production-Ready Features):
- ⚡ Parallel Indexing - Multi-threaded indexing using worker threads for massive performance gains
- 🎯 Interactive CLI Mode - REPL-style interface for codebase exploration with
/search, /ask, /stats commands
- 💾 Embedding Cache - Persistent caching with SHA-256 content hashing for 10x faster embedding generation
- 📦 Batch Processor - Efficient batch embedding with rate limiting and concurrency controlPrevious Updates (v3.0 - Code Analytics):
- 📊 Complexity Analysis - Cyclomatic & cognitive complexity metrics per function/file
- 🔍 Code Smells Detection - Identify long methods, god classes, duplicate code, deep nesting, magic numbers
- 🏗️ Pattern Recognition - Detect architectural (MVC, microservices) and design patterns (Singleton, Factory, Observer)
- ⚡ Analytics MCP Tools -
uce_analyze_complexity, uce_detect_smells, uce_detect_patterns for AI-powered code quality insightsPrevious Updates (v2.6 - AI-Powered Features):
- 🤖 AI-Powered Q&A - Ask natural language questions about your codebase and get intelligent answers with context
- 🌐 Multi-Source Indexing - Index code from filesystem, APIs, GitHub, or in-memory sources
- 🔌 Enhanced MCP Tools -
uce_ask tool for conversational codebase explorationPrevious Updates (v2.5 - Performance):
- 💾 State Persistence - 80% faster re-indexing by skipping unchanged files
- 📊 Enhanced Stats - Detailed tracking: new/updated/cached file counts
- 🚫 .uceignore Support - Fine-grained exclusion control alongside .gitignore
Core Features:
- 🔄 Auto-Indexing - Git pre-commit hook and background daemon for automatic UCE.md updates
- 🔌 Auto-Install Integrations -
uce install command for one-click AI assistant setup
- Tree-sitter AST Parsing - 20+ languages with accurate symbol extraction
- Incremental Indexing - Only re-index changed files
- Knowledge Graph - Navigate code relationships (callers, inheritance, dependencies)
- Hybrid Retrieval - BM25 + semantic search for best results
- MCP Server - Direct integration with Claude Code and other AI tools
- Watch Mode - Auto-update on file changes
- Single Universal Context File - One UCE.md works with any AI assistantFeatures
| Feature | Description |
|---------|-------------|
| AI-Powered Q&A | Ask questions about your codebase and get intelligent answers (v2.6+) |
| Multi-Source Indexing | Index from filesystem, GitHub, APIs, or in-memory code (v2.6+) |
| Tree-sitter Parsing | Accurate AST-based symbol extraction for 20+ languages |
| Knowledge Graph | Track function calls, class inheritance, and dependencies |
| Hybrid Search | BM25 lexical + semantic vector search |
| Incremental Index | Fast updates - only re-parse changed files |
| State Persistence | 80% faster re-indexing with file hash caching (v2.5+) |
| MCP Server | Model Context Protocol server for AI assistants |
| Watch Mode | Real-time index updates on file changes |
| Universal Output | Single UCE.md file works with Claude, Cursor, Copilot, any LLM |
| 100% Local | No cloud, no uploads, complete privacy |
Supported Languages
TypeScript, JavaScript, Python, Rust, Go, Java, C#, Ruby, PHP, Swift, Kotlin, Scala, C, C++, and more.
Installation
`bash
npm
npm install universal-context-engineyarn
yarn add universal-context-enginepnpm
pnpm add universal-context-engineglobal install
npm install -g universal-context-engine
`See INSTALLATION.md for detailed setup instructions.
Quick Start
$3
`bash
npx uce init
`Creates:
`
your-project/
├── .uce/
│ ├── index.json # Codebase index
│ └── state.json.gz # State for fast re-indexing (v2.5+)
├── .contextignore # File exclusion patterns (auto-created)
├── .uceignore # UCE-specific exclusions (optional, v2.5+)
└── UCE.md # Universal context file (works with any AI)
`Note: UCE respects
.gitignore, .contextignore, and .uceignore (v2.5+) for file exclusions.$3
`bash
npx uce stats
`$3
`bash
npx uce search "authentication"
`$3
Choose one of these options to keep UCE.md updated automatically:
Option A: Git Hook (Recommended)
`bash
npx universal-context-engine hook
`
Auto-indexes before every commit. No background process needed.Option B: Background Daemon
`bash
npx universal-context-engine daemon
`
Watches files and updates UCE.md on every save.Option C: Watch Mode (Interactive)
`bash
npx uce watch
`
Runs in foreground with live output.Commands
| Command | Description |
|---------|-------------|
|
uce init | Initialize UCE in a project |
| uce install | Auto-install AI assistant integrations |
| uce hello | Guided onboarding for new users |
| uce index | Re-index the codebase |
| uce generate | Regenerate UCE.md from existing index |
| uce watch | Watch for changes and auto-update |
| uce stats | Show index statistics |
| uce search | Search codebase with BM25 |
| uce query | Query symbols and files |
| uce graph | Export knowledge graph (JSON/DOT/Mermaid) |
| uce related | Find related symbols |
| uce callers | Find function callers |
| uce inheritance | Show class hierarchy |
| uce serve | Start MCP server |
| uce config | Manage configuration |
| uce info | Show version and system info |
| uce clean | Remove generated files |
| uce export | Export index as JSON |
| uce diff | Show changes since last index |
| uce hook | Install git pre-commit hook for auto-indexing |
| uce daemon | Start/stop background file watcher |$3
`bash
Search for authentication code
npx uce search "login validation"Find all callers of a function
npx uce callers handleSubmitShow class inheritance tree
npx uce inheritance BaseControllerExport graph as Mermaid diagram
npx uce graph --format mermaid > architecture.mdStart MCP server on custom port
npx uce serve --port 4000Guided setup for new users
npx uce helloAuto-install AI assistant integrations (use full package name with npx)
npx universal-context-engine install # All assistants
npx universal-context-engine install --assistant claude # Claude Code only
npx universal-context-engine install --assistant cursor # Cursor IDE only
npx universal-context-engine install --assistant claude --global # Global Claude commandsAuto-indexing options
npx universal-context-engine hook # Install git pre-commit hook
npx universal-context-engine daemon # Start background watcher
npx universal-context-engine daemon --stop # Stop background watcher
`Configuration
Create
.ucerc.json:`json
{
"projectName": "my-project",
"ignore": ["/dist/", "*/.min.js"],
"priorityFiles": ["README.md", "src/index.ts"],
"maxTokens": 50000,
"enableEmbeddings": false,
"output": {
"uceMd": true
},
"state": {
"enabled": true,
"path": ".uce/state.json.gz",
"autoExport": true
},
"qa": {
"provider": "anthropic",
"model": "claude-3-5-sonnet-20241022",
"maxContextTokens": 4000,
"maxResponseTokens": 2000
}
}
`New in v2.6: The
qa configuration enables AI-powered question answering about your codebase.New in v2.5: The
state configuration enables state persistence for 80% faster re-indexing.Generate default config:
`bash
npx uce config --init
`API
$3
`typescript
import { ContextEngine } from 'universal-context-engine';const engine = new ContextEngine({
projectRoot: '/path/to/project',
enableEmbeddings: false,
});
await engine.initialize();
await engine.index();
// AI-powered Q&A (v2.6+)
const qaResult = await engine.ask('How does authentication work?');
console.log(qaResult.answer);
console.log(
Confidence: ${qaResult.confidence});
console.log(Sources: ${qaResult.sources.length} files);// Retrieve context for a query
const context = await engine.retrieve('how does auth work?');
// Search symbols
const results = engine.searchSymbols('User');
// Knowledge graph queries
const callers = engine.findCallers('handleLogin');
const hierarchy = engine.getInheritance('BaseService');
const deps = engine.getDependencies('src/auth.ts');
`$3
`typescript
import { Indexer, ContextGenerator, indexProject } from 'universal-context-engine';// Quick one-liner
await indexProject('/path/to/project');
// Or manual control
const indexer = new Indexer({ projectRoot: '/path/to/project' });
const index = await indexer.index();
const generator = new ContextGenerator({ projectRoot: '/path/to/project', index });
generator.generateAll();
`AI Assistant Integrations
UCE works with all major AI coding assistants. See ai-integrations/ for configuration files and commands.
| Assistant | Integration |
|-----------|-------------|
| Claude Code | MCP server + slash commands |
| Cursor | .cursorrules + UCE.md |
| GitHub Copilot | copilot-instructions.md |
| Cline | Custom commands |
| Continue | Context provider |
| Others | Universal YAML spec |
$3
`bash
For Cursor - copy UCE.md as rules
cp UCE.md .cursorrulesFor Copilot - copy to instructions
mkdir -p .github && cp UCE.md .github/copilot-instructions.md
`MCP Server
UCE includes a Model Context Protocol server for direct AI assistant integration.
$3
`bash
npx uce serve --port 3333
`$3
Add to your MCP configuration:
`json
{
"mcpServers": {
"uce": {
"command": "npx",
"args": ["uce", "serve"],
"cwd": "/path/to/project"
}
}
}
`$3
| Tool | Description |
|------|-------------|
|
uce_ask | NEW v2.6 - Ask natural language questions about the codebase |
| uce_get_context | Get relevant context for a query |
| uce_search | Search symbols |
| uce_find_related | Find related code |
| uce_get_callers | Find function callers |
| uce_get_inheritance | Get class hierarchy |
| uce_get_dependencies | Get file dependencies |
| uce_graph_stats | Knowledge graph statistics |
| uce_health | Server health check |Auto-Indexing
UCE v2.4 introduces automatic indexing so your UCE.md stays up-to-date without manual intervention.
$3
`bash
Install the hook
npx universal-context-engine hookUCE.md will auto-update before every commit
git commit -m "your changes" # UCE runs automatically!Remove the hook
npx universal-context-engine hook --uninstall
`Benefits:
- No background process needed
- UCE.md is always committed with your code changes
- Works with any git workflow
$3
`bash
Start daemon
npx universal-context-engine daemonCheck status
npx universal-context-engine daemon --statusStop daemon
npx universal-context-engine daemon --stop
`Benefits:
- Real-time updates on every file save
- Logs stored in
.uce/daemon.log
- Perfect for active development sessions$3
After installing UCE integrations, use these slash commands:
-
/uce:hook - Install git pre-commit hook
- /uce:daemon - Start background daemon
- /uce:daemon-stop - Stop the daemonArchitecture
`
┌─────────────────────────────────────────────────────────────┐
│ Universal Context Engine v2.4 Architecture │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Tree-sitter │───▶│ Incremental │───▶│ Knowledge │ │
│ │ Parser │ │ Indexer │ │ Graph │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Context │◀───│ Hybrid │◀───│ BM25 │ │
│ │ Engine │ │ Retriever │ │ Index │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ MCP Server │ │ Generator │ │ Auto-Index │ │
│ │ │ │ (UCE.md) │ │ Hook/Daemon │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
`Comparison
| Feature | UCE | Cloud Alternatives |
|---------|-----|-------------------|
| Data location | Your project | Their cloud |
| Privacy | 100% local | Code uploaded |
| Works offline | Yes | No |
| Open source | Yes | Usually no |
| Cost | Free | Paid |
| Any LLM support | Yes | Vendor locked |
Contributing
We welcome contributions! See CONTRIBUTING.md for guidelines.
`bash
git clone https://github.com/Eskapeum/Context-Engine.git
cd Context-Engine
npm install
npm run build
npm test
``MIT License - see LICENSE
- Installation Guide
- AI Integrations
- Contributing
- Changelog
- GitHub Issues
---
Built with care for the AI-native developer community
Part of the Lyceum AI Academy mission