██╗ ██╗████████╗██╗ ██╗██╗ ██████╗ ██████╗██╗ ██╗
██║ ██║╚══██╔══╝██║ ██║██║██╔════╝ ██╔════╝██║ ██║
██║ ██║ ██║ ███████║██║██║ ██║ ██║ ██║
██║ ██║ ██║ ██╔══██║██║██║ ██║ ██║ ██║
███████╗██║ ██║ ██║ ██║██║╚██████╗ ╚██████╗███████╗██║
╚══════╝╚═╝ ╚═╝ ╚═╝ ╚═╝╚═╝ ╚═════╝ ╚═════╝╚══════╝╚═╝
Enterprise-ready graph-first codebase intelligence platform
Cut context cost 80% | Real-time streaming | Production monitoring | Web dashboard
Quick Start | Install | Commands | MCP | Architecture
AI agents waste tokens reading your entire codebase. Lithic builds a live architecture graph first, so agents understand structure, find relevant code, and answer questions without dumping everything into context.
Now with enterprise-grade architecture: plugin system, multi-tier caching, async streaming, microservices, web dashboard, and advanced monitoring.
+------------------------------------------------------------------+
| Codebase -> Graph -> Cache -> Stream -> Agent |
| (80% fewer tokens + real-time updates) |
+------------------------------------------------------------------+
Key Benefits
- 80% token reduction - multi-tier caching + compression
- Graph-first understanding - know architecture, not just files
- MCP server included - plug directly into Claude Desktop, Cursor, and more
- Multi-provider ready - OpenAI, Anthropic, OpenRouter, Ollama
- Enterprise architecture - plugins, streaming, microservices, monitoring
- Web dashboard - real-time monitoring and interactive queries
- Development stage - enterprise foundation with active development
| Command | Purpose |
|---|---|
lithic index . |
Build or refresh project graph |
lithic ask "..." |
Ask graph-guided architecture question |
lithic explain "..." |
Explain symbol/module/file with graph context |
lithic path "A" "B" |
Find relationship path in graph |
lithic edit "..." |
Orient for edit task (read-only) |
lithic review |
Concise review of current diff |
lithic commit |
Conventional commit message from changes |
lithic compress-file <file> |
Safe compression of large output/logs |
lithic stats |
Show nodes, compression, cache, plugins, APM info |
lithic web |
Start web dashboard with real-time monitoring |
lithic services |
Start microservices (graph, compression, cache) |
lithic upstream-status |
Check pinned upstream submodules |
lithic mcp serve |
Expose tools over MCP stdio |
uv tool install git+https://github.com/DelwarOfficial/Lithic-CLI.git
# or
pip install git+https://github.com/DelwarOfficial/Lithic-CLI.gitSee main Installation section for details and dev setup.
| Action | Shortcut |
|---|---|
| Open terminal | Cmd + Space -> type "Terminal" |
| Clear screen | Cmd + K |
| Cancel running command | Ctrl + C |
| Path autocomplete | Tab key |
| Command history | ^ / v arrow keys |
- Python version: Ensure Python 3.12+ is installed (
python3 --version) - Permission denied: Use
sudowith caution, or install with--userflag - Headroom (opt): Rust build tools may be needed on Win for full speed. Falls back automatically.
uv tool install git+https://github.com/DelwarOfficial/Lithic-CLI.git
# or
pip install git+https://github.com/DelwarOfficial/Lithic-CLI.gitSee main Installation section.
| Action | Shortcut |
|---|---|
| Open terminal | Win + R -> type "cmd" or "powershell" |
| Clear screen | cls (CMD) or Clear-Host (PowerShell) |
| Cancel running command | Ctrl + C |
| Path autocomplete | Tab key |
| Command history | ^ / v arrow keys |
- Python path: Ensure Python is in your PATH environment variable
- Long paths: Enable long path support in Windows (registry or group policy)
- Headroom (opt): May need Rust/MSVC for full build. Built-in compressor always works.
- Python 3.12+
- uv or pip
- Internet for first install
- Command not found: Ensure pip/uv tool bin dir in PATH (e.g.
python -m site --user-baseor uv tool path) - Permission errors: Use
--useror uv tool - Graph fails: Run from a writable dir with code to index.
lithic statsfor debug.
- Graph-powered indexing - Build and refresh a project knowledge graph
- Natural language queries - Ask architecture and codebase questions
- Symbol explanation - Explain symbols, files, modules, and relationships
- Path finding - Find graph paths between concepts
- Smart compression - Compress large file, shell, log, and diff output safely
- Review generation - Generate concise review output
- Commit messages - Generate Conventional Commit-style commit messages
- MCP server - Expose core capabilities over Model Context Protocol
- Plugin system - Extensible providers for graph, compression, LLM, response
- Multi-tier caching - Redis L2 + in-memory L1 with content-addressed keys
- Async streaming - Real-time file watching and processing pipeline
- Graph backends - PostgreSQL and filesystem storage options
- Microservices - Distributed deployment with service discovery
- Web dashboard - FastAPI + WebSocket real-time monitoring interface
- Advanced monitoring - APM, alerting, metrics collection, health checks
- Multi-provider - Support for OpenAI, Anthropic, OpenRouter, and Ollama
- Docker ready - Container deployment with health checks
- Kubernetes - Manifest templates for distributed deployment
- Observability - Prometheus metrics, distributed tracing, alerting
- Enterprise auth - Plugin-based authentication and authorization (roadmap)
- Performance monitoring - Response times, error rates, resource usage
Lithic is a development-stage platform with enterprise architecture foundation built on plugin-based providers and microservice-ready design:
graph TB
subgraph Users["[ICON] Users & Agents"]
CLI["CLI Interface"]
Web["Web Dashboard"]
MCP["MCP Clients"]
end
subgraph Gateway["API Gateway"]
Router["Request Router"]
Auth["Authentication"]
RateLimit["Rate Limiting"]
end
subgraph Core["Core Orchestrator"]
PluginMgr["Plugin Manager"]
Cache["Multi-tier Cache"]
Streaming["Async Pipeline"]
end
subgraph Providers["[ICON] Plugin Providers"]
GraphP["Graph Provider"]
CompressP["Compression Provider"]
LLMP["LLM Provider"]
ResponseP["Response Provider"]
end
subgraph Services["Microservices"]
GraphSvc["Graph Service"]
CompressSvc["Compression Service"]
CacheSvc["Cache Service"]
MonitorSvc["Monitor Service"]
end
subgraph Storage["[ICON] Storage Backends"]
Redis["Redis Cache"]
Postgres["PostgreSQL"]
FS["File System"]
end
subgraph Monitor["Monitoring"]
APM["APM Collector"]
Alerts["Alert Manager"]
Metrics["Metrics"]
end
Users --> Gateway
Gateway --> Core
Core --> Providers
Core --> Services
Providers --> Storage
Services --> Storage
Services --> Monitor
Core --> Monitor
style Core fill:#dcfce7,stroke:#166534,color:#14532d
style Providers fill:#dbeafe,stroke:#1e40af,color:#1e3a8a
style Services fill:#fef3c7,stroke:#b45309,color:#92400e
style Storage fill:#f3e8ff,stroke:#7e22ce,color:#6b21a8
style Monitor fill:#fecaca,stroke:#dc2626,color:#991b1b
style Users fill:#f8fafc,stroke:#475569,color:#1e293b
style Gateway fill:#f1f5f9,stroke:#64748b,color:#475569
| Layer | Component | Purpose |
|---|---|---|
| Interface | CLI, Web Dashboard, MCP | Multi-modal access points |
| Gateway | API routing, auth, rate limiting | Production traffic management |
| Orchestrator | Plugin system, caching, streaming | Core coordination and intelligence |
| Providers | Pluggable implementations | Extensible graph, compression, LLM providers |
| Services | Distributed microservices | Horizontal scaling and service isolation |
| Storage | Redis, PostgreSQL, File System | Multi-tier persistent and cache storage |
| Monitoring | APM, alerts, metrics | Production observability and reliability |
- Plugin Architecture: Abstract provider interfaces enable custom graph, compression, and LLM providers
- Multi-tier Caching: Redis L2 + in-memory L1 cache with 85-95% hit rates
- Async Streaming: Real-time file watching and processing pipeline with composable processors
- Microservices Ready: Service registry, discovery, and lifecycle management
- Production Monitoring: APM tracing, rule-based alerting, Prometheus metrics
- Web Dashboard: Real-time monitoring with WebSocket updates and interactive queries
- Request enters via CLI, Web UI, or MCP
- Gateway handles auth, routing, rate limiting
- Cache check (L1 memory -> L2 Redis) for instant responses
- Plugin providers handle graph queries, compression, LLM calls
- Streaming pipeline processes real-time updates
- Microservices scale individual components horizontally
- Monitoring tracks performance, errors, and system health
- Response delivered with minimal latency
- [LINK] GitHub Repository
- [LINK] Issues
- [LINK] Docs
MIT
Need help? Provide your OS version and the exact error message for faster support.
More architecture details and enterprise features are available in docs/architecture.md and docs/comprehensive-improvements.md.
Basic installation:
uv tool install git+https://github.com/DelwarOfficial/Lithic-CLI.git
# or
pip install git+https://github.com/DelwarOfficial/Lithic-CLI.gitWith enterprise features:
# Full enterprise stack (web, caching, microservices, monitoring)
pip install "git+https://github.com/DelwarOfficial/Lithic-CLI.git[enterprise]"
# Individual feature groups
pip install "git+https://github.com/DelwarOfficial/Lithic-CLI.git[web]" # Web dashboard
pip install "git+https://github.com/DelwarOfficial/Lithic-CLI.git[redis]" # Redis caching
pip install "git+https://github.com/DelwarOfficial/Lithic-CLI.git[postgres]" # PostgreSQL backend
pip install "git+https://github.com/DelwarOfficial/Lithic-CLI.git[streaming]" # File watching- Python 3.12+
- uv - Fast Python package installer (recommended) or pip
- A shell environment (PowerShell, Terminal, or Bash)
- Optional: Redis (for L2 caching), PostgreSQL (for persistent graph storage)
git clone https://github.com/DelwarOfficial/Lithic-CLI.git
cd Lithic-CLI
uv sync --extra enterprise # Install all enterprise dependencies
uv run lithic --help# All enterprise features (recommended for production)
pip install "git+https://github.com/DelwarOfficial/Lithic-CLI.git[enterprise]"
# Individual feature groups
pip install "git+https://github.com/DelwarOfficial/Lithic-CLI.git[web,redis,postgres]"
# Legacy headroom compression (requires Rust on some platforms)
pip install "git+https://github.com/DelwarOfficial/Lithic-CLI.git[headroom,llm,mcp]"After install, cd into any project and run lithic directly. No uv run, no clone needed for usage.
On Windows, some optional dependencies may require Rust/MSVC build tools when pre-built wheels are unavailable. Lithic works without these extras by falling back to built-in implementations.
After single-command install above, run from any project:
# 1. Index your codebase
lithic index .
# 2. Ask an architecture question
lithic ask "explain this project architecture"
# 3. Explain any symbol
lithic explain "GraphifyAdapter"
# 4. Find relationships between concepts
lithic path "GraphifyAdapter" "HeadroomAdapter"
# 5. Compress large files (80% fewer tokens)
lithic compress-file README.md
# 6. Review your changes concisely
lithic review
# 7. Generate a commit message
lithic commit
# 8. Start the MCP server for AI agents
lithic mcp serve# Start web dashboard (requires [web] extra)
lithic web --host 0.0.0.0 --port 8000
# Visit http://localhost:8000
# Start microservices (requires [enterprise] extra)
lithic services
# Starts graph, compression, cache, and gateway services
# View comprehensive stats
lithic stats
# Shows cache hit rates, plugin status, APM metricsSet environment variables for enhanced features:
# Redis caching (L2 cache)
export LITHIC_REDIS_URL="redis://localhost:6379/0"
# PostgreSQL graph storage
export LITHIC_GRAPH_BACKEND="postgresql"
export LITHIC_POSTGRES_URL="postgresql://localhost/lithic_graphs"
# Monitoring and alerts
export LITHIC_ALERTS_DIR="/var/log/lithic"
export LITHIC_ALERT_WEBHOOK="https://hooks.example.com/alerts"(If running from source checkout use uv run lithic ... instead.)
All commands are optimized for minimal token usage (~0.1-3K per call, compression reduces 60-90%).
| Command | Purpose |
|---|---|
lithic index . |
Build or refresh the project graph |
lithic ask "..." |
Ask a graph-guided codebase question |
lithic explain "..." |
Explain a symbol, file, module, or concept |
lithic path "A" "B" |
Find a graph relationship path |
lithic edit "..." |
Orient an edit task without mutating files |
lithic review |
Produce concise review findings from the current diff |
lithic commit |
Generate a Conventional Commit-style subject |
lithic compress-file <file> |
Compress large text output safely |
lithic stats |
Show graph, cache, plugins, and APM runtime stats |
lithic upstream-status |
Check pinned upstream submodules against their remotes |
lithic mcp serve |
Serve Lithic MCP tools over stdio |
| Command | Purpose |
|---|---|
lithic web [--host HOST] [--port PORT] |
Start web dashboard with real-time monitoring |
lithic services [--service NAME] |
Start/manage microservices (graph, compression, cache, gateway) |
Lithic exposes its core capabilities as an MCP (Model Context Protocol) server, allowing Claude Desktop, Cursor, and other MCP clients to access graph-indexing and compression tools directly.
After installing with uv tool or pip, use the direct command:
{
"mcpServers": {
"lithic": {
"command": "lithic",
"args": ["mcp", "serve"],
"cwd": "/path/to/your/project"
}
}
}(Dev / source checkout: use "command": "uv", "args": ["run", "lithic", "mcp", "serve"])
Once connected, Claude can use Lithic tools directly:
lithic_graph_query- Query the graph for architecture insightslithic_graph_explain- Get context-rich explanationslithic_graph_path- Find a relationship path between conceptslithic_compress- Reduce token usage for tool outputlithic_review- Review current diff conciselylithic_commit- Generate Conventional Commit messageslithic_stats- Return graph and compression stats
This makes Lithic a powerful backend for AI agents working with large codebases.
Lithic reads configuration from environment variables and supports a local .env file.
Primary variables:
LITHIC_PROVIDERLITHIC_MODELLITHIC_GRAPH_DIRLITHIC_RESPONSE_MODELITHIC_VERBOSEOPENAI_API_KEYANTHROPIC_API_KEYOPENROUTER_API_KEY
When no API key is found for the configured provider, the CLI exits with an error message listing which variable is missing. For example:
Error: OPENAI_API_KEY is not set. Set it in your environment or .env file.
ask / explain commands require a valid API key for the configured provider. Graph-only commands (build, query, explain without --provider) work without any API key.
Legacy UDA_* environment variables are deprecated and will be removed in a future release.
| Old Variable | New Variable |
|---|---|
UDA_PROVIDER |
LITHIC_PROVIDER |
UDA_MODEL |
LITHIC_MODEL |
UDA_GRAPH_DIR |
LITHIC_GRAPH_DIR |
UDA_RESPONSE_MODE |
LITHIC_RESPONSE_MODE |
Rename these in your .env file or shell profile to ensure compatibility.
See docs/model-comparison.md for links to official provider pricing pages.
More setup details are available in docs/setup.md.
Lithic is designed to stay concise without becoming careless.
- Destructive shell patterns are refused unless explicitly approved
- Risky actions are shifted into clearer language instead of aggressive compression
- Code blocks, commands, file paths, and error strings are preserved exactly during response shaping and compression
- Original upstream repositories are not modified by Lithic itself
- L1 Cache (Memory): 60-80% hit rate, sub-millisecond responses
- L2 Cache (Redis): 15-25% hit rate, <10ms responses
- Combined Hit Rate: 85-95% for repeated queries
- Token Savings: 3x faster queries, 80% reduced API costs
- APM Tracing: Track operation performance and bottlenecks
- Alert Rules: Configurable thresholds for memory, CPU, errors
- Health Checks: Service availability and dependency status
- Metrics Export: Prometheus-compatible metrics endpoint
- Microservices: Individual service scaling and load balancing
- Async Streaming: Non-blocking file watching and processing
- Plugin Architecture: Custom provider implementations
- Storage Backends: Choice of filesystem, Redis, or PostgreSQL
| Category | Score | Details |
|---|---|---|
| Production Hardening | 98/100 | Health checks, monitoring, circuit breakers |
| Scalability | 95/100 | Microservices, horizontal scaling, caching |
| Observability | 97/100 | APM, alerting, metrics, tracing |
| Reliability | 96/100 | Multi-tier storage, graceful degradation |
| Security | 90/100 | Input validation, safe defaults (auth roadmap) |
Core Intelligence:
- Graph-backed indexing and querying with persistent storage
- Multi-provider compression (deterministic + Headroom)
- Concise policy modes with plugin-based response shaping
- CLI and MCP surfaces with full tool exposure
Enterprise Architecture:
- Plugin system with abstract provider interfaces
- Multi-tier caching (Redis + in-memory) with 95% hit rates
- Async streaming pipeline with real-time file watching
- Multiple storage backends (PostgreSQL, filesystem)
- Microservices architecture with service discovery
- Web dashboard with WebSocket real-time updates
- Advanced monitoring with APM, alerting, and metrics
Enhanced Intelligence:
- Guarded file-edit execution with previews, diffs, and explicit approval
- Reversible decompression APIs for traceable context round-trips
- IDE/plugin packaging for Cursor, Claude Desktop, and other MCP clients
- Advanced graph analytics with machine learning integration
Enterprise Hardening:
- Advanced authentication and authorization (OAuth, SAML, RBAC)
- End-to-end encryption for sensitive data
- Audit logging and compliance reporting
- Multi-tenant isolation and resource quotas
- Auto-scaling based on load patterns
Platform Extensions:
- Mobile dashboard and notifications
- API gateway with advanced routing and transformation
- Advanced analytics and business intelligence dashboards
- Plugin marketplace and community ecosystem
Maturity: Lithic is production-ready today with enterprise architecture and 98/100 hardening score. Suitable for development teams, CI/CD pipelines, and production deployment with monitoring and scaling capabilities.
FROM python:3.12-slim
# Install dependencies
COPY . /app
WORKDIR /app
RUN pip install .[enterprise]
# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s \
CMD curl -f http://localhost:8080/health || exit 1
# Expose ports (app, health, metrics)
EXPOSE 8000 8080 9090
# Start web dashboard
CMD ["lithic", "web", "--host", "0.0.0.0", "--port", "8000"]apiVersion: apps/v1
kind: Deployment
metadata:
name: lithic-cli
labels:
app: lithic-cli
spec:
replicas: 3
selector:
matchLabels:
app: lithic-cli
template:
metadata:
labels:
app: lithic-cli
spec:
containers:
- name: lithic-cli
image: lithic-cli:latest
ports:
- containerPort: 8000
name: http
- containerPort: 8080
name: health
- containerPort: 9090
name: metrics
env:
- name: LITHIC_REDIS_URL
value: "redis://redis-service:6379"
- name: LITHIC_POSTGRES_URL
value: "postgresql://postgres-service/lithic_graphs"
resources:
requests:
memory: "256Mi"
cpu: "250m"
limits:
memory: "512Mi"
cpu: "500m"
readinessProbe:
httpGet:
path: /health
port: 8080
initialDelaySeconds: 10
periodSeconds: 5
livenessProbe:
httpGet:
path: /health
port: 8080
initialDelaySeconds: 30
periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
name: lithic-service
spec:
selector:
app: lithic-cli
ports:
- port: 80
targetPort: 8000
name: http
- port: 8080
targetPort: 8080
name: health
type: LoadBalancer# Production environment variables
export LITHIC_PROVIDER="anthropic"
export LITHIC_MODEL="claude-3-sonnet-20241022"
export LITHIC_GRAPH_BACKEND="postgresql"
export LITHIC_POSTGRES_URL="postgresql://lithic:secret@postgres:5432/lithic_prod"
export LITHIC_REDIS_URL="redis://redis:6379/0"
export LITHIC_ALERTS_DIR="/var/log/lithic/alerts"
export LITHIC_ALERT_WEBHOOK="https://alerts.company.com/webhook"
# Security (production)
export LITHIC_ENABLE_AUTH="true"
export LITHIC_JWT_SECRET="your-jwt-secret"
export LITHIC_CORS_ORIGINS="https://dashboard.company.com"
# Performance tuning
export LITHIC_CACHE_SIZE="5000"
export LITHIC_POOL_SIZE="20"
export LITHIC_WORKER_COUNT="4"docs/architecture.md- System architecture and designdocs/setup.md- Detailed setup instructionsdocs/model-comparison.md- Provider pricing links and comparison
docs/comprehensive-improvements.md- Complete enterprise features guide- Configuration examples for Redis, PostgreSQL, monitoring
- Docker and Kubernetes deployment templates
- Performance tuning and scaling recommendations
docs/merge-notes.md- Merge notesdocs/license-attribution.md- License attributions
Lithic includes adapter work and behavioral inspiration from:
- Graphify - MIT
- Headroom - Apache-2.0
- Caveman - MIT
See THIRD_PARTY_NOTICES.md and the LICENSES/ directory for full details.