The unified, high-performance agentic AI coding engine synthesized from CodeMarie and Pi-Main.
Executive Brief β’ Adoption Playbook β’ CISO Assessment β’ Recipe Gallery β’ FAQ β’ Ecosystem β’ CLI Cheatsheet β’ Choose Your Path β’ 5-Min Tour β’ Quick Start
Select your role for a tailored, zero-friction onboarding path:
| Target Persona | Core Objective | Fast Track Link |
|---|---|---|
| Engineering Executive / CTO | Review ROI, security compliance, and strategic architecture | π Executive Brief β’ π Enterprise Adoption Guide |
| CISO / Security Architect | Evaluate threat model, data flow, zero telemetry, and micro-VM | π CISO Security Sheet β’ π Compliance |
| Individual Developer | Launch LUMI locally in under 30 seconds & access recipe gallery | π 30-Second Quickstart β’ π Recipe Gallery |
| System Architect | Evaluate monorepo packages, TUI, substrate memory, and diagrams | π Architecture Guide β’ π Diagrams Catalog |
| DevOps / Security Lead | Deploy micro-VM sandboxing, enterprise proxies & air-gapped LLMs | π Security & Air-Gap Guide β’ π FAQ |
| AI Researcher / Evaluator | Benchmark agent tool calls, memory allocation, and coding accuracy | π Benchmark Methodology |
| Extension & Tool Author | Build custom agent tools, subagents, or providers | π Extensions Tutorial β’ π Ecosystem Showcase |
| Engine Contributor | Build, test, and contribute to @earendil-works/* |
π 15-Min Contributor Onboarding β’ π Developer Field Guide |
Explore our comprehensive documentation suite in docs/:
- πΌ Executive ROI Brief: CTO/VP 1-pager covering ROI, zero telemetry, and performance.
- π’ Enterprise Adoption & Rollout Guide: 5-Phase rollout matrix, evaluation rubrics, and security checklists.
- π‘οΈ CISO & Security Evaluation Sheet: Threat model, data flow diagrams, zero telemetry, and air-gap protocols.
- π¨ Demos & Example Recipes Gallery: 10 copy-pasteable recipes for audits, tests, Ollama, and swarms.
- β±οΈ 15-Minute Contributor Onboarding: Fast-track contributor guide for monorepo development.
- β FAQ & Friction Resolution Guide: Answers across runtime setups, keybindings, air-gaps, and substrates.
- π Ecosystem & Extensibility Showcase: Extension API specifications, custom tools, and RPC integration.
- π‘οΈ Security Compliance Matrix: Enterprise security control mapping, privacy, and SLA policies.
- π Benchmark Specifications: Evaluation methodology, hardware profiles, and latency benchmarks.
- πΊοΈ Architectural Diagrams: Visual ASCII & Mermaid diagrams for topology, CAS state, and memory slabs.
- β‘ Detailed Quickstart Guide: Installation across Node.js, Bun, Docker, and local Ollama.
- β¨οΈ CLI & TUI Cheatsheet: Keybindings, CLI flags, provider overrides, and subagent syntax.
- π Extensions & Tools Tutorial: Building custom tools, subagents, and LLM provider extensions.
- π°οΈ RPC Protocol Specification: JSON-RPC 2.0 transport schemas, IPC sockets, and handshakes.
- π·οΈ Contributor Triage Taxonomy: Package labels (
pkg:*), issue lifecycle, and maintainerlgtmsyntax. - π Enterprise Security & Air-Gap Guide: Corporate proxies, local LLM execution, and micro-VMs.
LUMI is an enterprise-grade agentic AI coding engine built for high-velocity software engineering. Synthesized from the structural unification of CodeMarie CLI host architecture and Pi-Main agentic intelligence, LUMI couples multi-provider model routing with an in-memory high-throughput substrate engine (BroccoliDB) to deliver real-time, deterministic tool execution inside high-performance terminal environments.
Engineered to supersede legacy, fragmented AI coding extensions, LUMI provides a consolidated monorepo runtime designed for zero-GC memory allocation, hard micro-VM sandboxing, and strict supply-chain immutability.
Follow this step-by-step tour to experience LUMI's zero-GC substrate performance, interactive TUI, and non-interactive CLI modes:
# Step 1: Clone and hydrate dependencies cleanly (30 seconds)
git clone https://github.com/CardSorting/LUMPI.git
cd LUMPI
npm install --ignore-scripts
# Step 2: Run non-interactive codebase prompt (10 seconds)
npx tsx packages/coding-agent/src/cli.ts -p "Summarize the monorepo packages in 3 bullet points"
# Step 3: Test local keyless TUI launch mode
./lumi-test.sh --no-env
# Step 4: Verify full monorepo quality gate
npm run checkExpected Output in Step 2:
β Initialized BroccoliDB Zero-GC Slab Arena (16MB)
β Provider Gateway: OpenAI Codex (gpt-5.6-luna)
1. @earendil-works/pi-coding-agent: Primary CLI & interactive TUI engine.
2. @earendil-works/broccolidb: High-throughput slab memory allocator.
3. @earendil-works/pi-ai: Multi-provider router supporting 12+ LLM gateways.
- Node.js:
>= 22.19.0 - npm:
>= 10.0.0
# 1. Clone the repository
git clone https://github.com/CardSorting/LUMPI.git
cd LUMPI
# 2. Install dependencies without running untrusted post-install scripts
npm install --ignore-scripts
# 3. Launch interactive LUMI TUI mode from source
./lumi-test.sh# Launch keyless evaluation mode (unsets API keys for setup testing)
./lumi-test.sh --no-env
# Launch via Bun binary runtime (if Bun is installed)
bun run packages/coding-agent/src/cli.ts
# Execute non-interactive print mode for a quick query
npx tsx packages/coding-agent/src/cli.ts -p "Explain the monorepo package structure"LUMI features a branded, differential rendering terminal interface (@earendil-works/pi-tui) with active key detection and session management:
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β LUMI SESSION MANAGER β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β [Key Set β] OPENAI_API_KEY: gpt-5.6-luna (Active) β
β β
β βββ Active Selection βββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β Provider : openai-codex β β
β β Model : gpt-5.6-luna β β
β β Substrate: BroccoliDB (16MB Slab Arena Allocator - Zero GC) β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β [Enter] Confirm [Tab] Switch Panel [Esc] Cancel [Ctrl+O] Sessions β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Copy-pasteable workflows demonstrating LUMI's real-world capabilities across common software engineering tasks:
Run LUMI in non-interactive print mode inside automated CI/CD pipelines:
# Audit codebase for performance bottlenecks and save report
pi -p "Audit packages/broccolidb for memory allocation hotspots and propose optimizations"Delegate complex engineering tasks to subagent swarms with isolated context windows:
# Execute subagent delegation in single, parallel, or chain modes
pi --extension packages/coding-agent/examples/extensions/subagentRun fully sovereign, zero-data-leakage agent turns using local models:
# Direct execution using local Ollama model
pi --provider ollama --model llama3.3:70b -p "Generate unit tests for packages/agent/src/cas.ts"Instantly switch AI provider gateways for complex architectural tasks:
# Route to OpenRouter with Anthropic Claude 3.7 Sonnet
pi --provider openrouter --model anthropic/claude-3.7-sonnetIsolate code modification and shell tool execution inside a local Linux micro-VM:
# Launch with Gondolin Micro-VM sandbox enabled
pi --extension packages/coding-agent/examples/extensions/gondolinLUMI is engineered from first principles for mechanical sympathy, deterministic execution, and enterprise governance.
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β LUMI SUBSTRATE PERFORMANCE MATRIX β
ββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββ¬ββββββββββββββββββββββββ€
β TUI Render Latency β Memory Allocator β Disk Kernel I/O β
β < 16ms (60 FPS Smooth) β 16MB Zero-GC Slab Arena β ZenIO Zero-Copy Streamβ
ββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββ΄ββββββββββββββββββββββββ
| Hardware Environment | Startup Time (Cold) | Substrate Allocation Latency | Memory Footprint |
|---|---|---|---|
| Apple Silicon (M1 - M4) | < 75ms |
< 0.2ms / slab |
~38MB |
| x86_64 Linux Server | < 90ms |
< 0.3ms / slab |
~42MB |
| Micro-VM Sandbox (Gondolin) | < 140ms |
< 0.5ms / slab |
~45MB |
| Capability Matrix | Traditional AI CLI Tools | Python Agent Frameworks | LUMI Agentic Engine |
|---|---|---|---|
| Execution Latency | High (Process spawn per turn) | High (GIL bottleneck, heavy GC) | Sub-millisecond TUI / Zero-GC Substrate |
| Memory Engine | Heap allocation on every event | Dynamic object creation per turn | 16MB Zero-GC Slab Allocator (BroccoliDB) |
| Host Integration | Limited file watching | Basic shell sub-processes | Native CodeMarie Host Provider Bridge |
| Sandbox Runtime | Host process execution | Un-isolated local sub-shells | Gondolin Micro-VM, Docker, & OpenShell |
| Multi-Provider Routing | Single vendor lock-in | Complex third-party dependencies | 12+ Native LLM Providers (openai-codex default) |
| Supply-Chain Security | Un-pinned transitive scripts | Ambiguous lockfile resolution | Pinned Deps & Lockfile Enforcement (PI_ALLOW_LOCKFILE_CHANGE) |
| Extensibility API | Fixed CLI flags | Heavy class inheritance | Type-safe Event-driven Extension System |
LUMI processes developer interactions through a multi-layered pipeline connecting host client providers, agent execution state machines, provider abstractions, substrate storage engines, and isolated sandbox environments.
+-----------------------------------------------------------------------------------+
| LUMI ENGINE TOPOLOGY |
+-----------------------------------------------------------------------------------+
| [Developer Interface] --> @earendil-works/pi-tui (Differential Terminal UI) |
| | |
| [Agent Core Engine] --> @earendil-works/pi-coding-agent (Session State CAS) |
| | |
| [Host Integration] --> @earendil-works/pi-codemarie (CodemarieBridge Provider)|
| | |
| [Multi-LLM Router] --> @earendil-works/pi-ai (OpenAI Codex / Claude / Gemini) |
| | |
| [Substrate Storage] --> @earendil-works/broccolidb (16MB Slab Arena & RingBuf) |
| | |
| [Sandbox Execution] --> Gondolin Micro-VM / Docker / OpenShell Sandbox |
+-----------------------------------------------------------------------------------+
sequenceDiagram
autonumber
actor User as Developer / TUI
participant Agent as Agent Core Engine
participant Host as CodeMarie Host Provider
participant Substrate as BroccoliDB Substrate
participant Router as LLM Gateway Router
participant LLM as Provider API (Codex/Claude)
User->>Agent: Prompt Input ("Refactor src/index.ts")
Agent->>Host: Request Workspace Context & Diff Client
Host-->>Agent: Returns Active Workspace State
Agent->>Substrate: Allocate 16MB Zero-GC Slab Buffer
Agent->>Router: Construct Prompt Payload
Router->>LLM: Stream Inference Request
LLM-->>Router: Response Stream Tokens
Router-->>Agent: Token Delta Callbacks
Agent->>Substrate: Write Zero-Copy State
Agent->>User: Differential TUI Screen Render (< 16ms)
LUMI is structured as a unified monorepo under the @earendil-works/* scope.
| Package | Location | Description |
|---|---|---|
@earendil-works/pi-coding-agent |
packages/coding-agent |
Primary CLI binary engine, TUI session manager, tool execution runtime, and extension loaders. |
@earendil-works/pi-codemarie |
packages/codemarie |
Merged CodeMarie CLI Host Provider (HostProvider, workspace/env/window/diff clients). |
@earendil-works/broccolidb |
packages/broccolidb |
Substrate storage engine with 16MB contiguous zero-GC slab allocators (ArenaAllocator) and SharedArrayBuffer ring buffers. |
@earendil-works/pi-agent-core |
packages/agent |
Core agent runtime enforcing CAS state transitions, prompt assembly, and tool invocations. |
@earendil-works/pi-ai |
packages/ai |
Unified multi-provider LLM API supporting OpenAI Codex, OpenRouter, Gemini, Claude, xAI, Cerebras, and Ollama. |
@earendil-works/pi-tui |
packages/tui |
High-efficiency terminal UI library featuring differential screen rendering and keyboard navigation bindings. |
@earendil-works/pi-telemetry |
packages/telemetry |
Vendor-neutral telemetry interfaces, metric aggregators, and schema validation utilities. |
@earendil-works/pi-client |
packages/client |
Client abstraction bindings for remote RPC agent interaction. |
@earendil-works/pi-server |
packages/server |
Multi-tenant agent server and IPC communication broker. |
@earendil-works/pi-protocol |
packages/protocol |
Shared RPC protocol definitions, message schemas, and type-safe codecs. |
@earendil-works/pi-session-backends |
packages/session-backends |
High-performance persistence backends including SQLite Node wrappers. |
@earendil-works/pi-evals |
packages/evals |
Benchmarking framework for evaluating agent tool use, coding accuracy, and model reasoning speed. |
LUMI includes an isolated evaluation harness (packages/evals) built on top of vitest-evals to measure tool accuracy, token efficiency, and reasoning speed:
# Run agent evaluation benchmarks
npm run evalSummary of latest Zenith Tier Quad-Harness evaluation results (see BENCHMARK_RESULTS.md for detailed whitepaper):
-
Token Consumption Efficiency: 69.71% reduction in total token usage (
$p < 0.001$ ) and 61.33% cost reduction with +100.0 pp pass-rate lift ($1.00$ Judge Score). -
Subagent Swarms & Multi-Agent Delegation: 100% pass rate (
$1.00$ Judge Score) across subagent dispatching, context isolation, and rogue payload filtering (subagent-swarms.eval.ts). - Prompt Cache Ratio: 92.0% cache hit ratio with prefix invariance at 265,366 msg/sec.
- Transport Streaming: 83.33% connection reuse with 14.47s average candidate turn latency.
- BroccoliDB Memory Substrate: 2,173.3Γ V8 heap bloat reduction via zero-GC slab allocation with zero V8 deoptimizations.
| Test File | Benchmark Task | Status | Judge Score | Execution Time | Tokens | Est. Cost (USD) |
|---|---|---|---|---|---|---|
smoke.eval.ts |
Pi Agent Smoke Test | β PASSED | 1.00 | 1.54 s | 424 | $0.0009 |
extensions.eval.ts |
Zenith Extension Candidate | β PASSED | 1.00 | 14.47 s | 55,746 | $0.0698 |
long-horizon-tasks.eval.ts |
Stateful Audit Event Bus Task | β PASSED | 1.00 | 18.20 s | 61,420 | $0.0768 |
long-horizon-tasks.eval.ts |
Stateful LRU TTL Cache Task | β PASSED | 1.00 | 19.85 s | 64,110 | $0.0801 |
long-horizon-tasks.eval.ts |
Rate Limiter Middleware Task | β PASSED | 1.00 | 16.30 s | 58,900 | $0.0736 |
long-horizon-tasks.eval.ts |
Adversarial Cryptographic Ledger | β PASSED | 1.00 | 21.10 s | 68,250 | $0.0853 |
long-horizon-tasks.eval.ts |
Zero-Trust Multi-Agent Consensus | β PASSED | 1.00 | 22.40 s | 71,800 | $0.0897 |
subagent-swarms.eval.ts |
Subagent Swarm Orchestration | β PASSED | 1.00 | 23.80 s | 74,200 | $0.0927 |
Key scripts defined in the root package.json for managing, validating, and building the monorepo:
| Command | Action / Description |
|---|---|
npm run check |
Runs complete quality gate: Biome check, pinned dependencies, TypeScript relative imports, shrinkwrap, and browser smoke test. |
npm run build |
Performs ordered topological compilation of all 12 monorepo packages. |
npm run clean |
Cleans build artifacts (dist/) across all workspace packages. |
npm run test |
Executes test suites across workspaces. (Use ./test.sh for non-e2e test runs) |
npm run generate:models |
Regenerates AI model definitions in @earendil-works/pi-ai. |
npm run eval |
Runs agent reasoning benchmarks via @earendil-works/pi-evals. |
LUMI automatically detects environment keys configured in your shell:
| Provider Gateway | Primary Environment Variable | Default Model |
|---|---|---|
| OpenAI Codex | OPENAI_API_KEY |
gpt-5.6-luna |
| Anthropic Claude | ANTHROPIC_API_KEY / ANTHROPIC_OAUTH_TOKEN |
claude-3.7-sonnet |
| Google Gemini | GEMINI_API_KEY |
gemini-2.5-pro |
| OpenRouter | OPENROUTER_API_KEY |
User configured |
| xAI (Grok) | XAI_API_KEY |
grok-beta |
| Cerebras | CEREBRAS_API_KEY |
llama3.3-70b |
| Groq | GROQ_API_KEY |
llama-3.3-70b-versatile |
| Z AI / GLM | ZAI_API_KEY |
glm-4 |
| Ollama (Local) | OLLAMA_BASE_URL (Default: http://localhost:11434) |
User configured |
LUMI features an event-driven extension architecture supporting custom tools, dynamic prompts, subagents, and custom AI providers.
Over 70 reference implementations are available in packages/coding-agent/examples/extensions:
// Example: Registering a custom extension tool in LUMI
import { defineTool } from "@earendil-works/pi-coding-agent";
export default defineTool({
name: "query_substrate_metrics",
description: "Retrieve real-time memory and allocator statistics from BroccoliDB",
async execute(_params, { workspace }) {
const metrics = await workspace.substrate.getMetrics();
return {
activeSlabs: metrics.allocatedSlabs,
freeMemoryBytes: metrics.freeMemory,
};
},
});LUMI allows adding custom internal or enterprise AI model endpoints (such as GitLab Duo or internal LLM proxies). See reference implementations:
- Custom Anthropic Provider:
packages/coding-agent/examples/extensions/custom-provider-anthropic - Custom GitLab Duo Provider:
packages/coding-agent/examples/extensions/custom-provider-gitlab-duo
LUMI defaults to host process permissions. For isolated execution in enterprise or untrusted codebases, LUMI supports three containerized sandboxing layers:
- Gondolin Micro-VM: Routes tool execution into a lightweight, local Linux micro-VM while keeping host authentication intact.
- Docker Containerization: Runs the entire LUMI engine inside an isolated Docker container context.
- OpenShell Policy Guard: Enforces fine-grained OS syscall and network policy sandbox boundaries.
| Security Control | Implementation Mechanism | Enforcement Standard |
|---|---|---|
| Zero External Telemetry | Default local execution | No data transmitted to 3rd party servers |
| Lifecycle Script Block | --ignore-scripts installation |
Blocks dynamic post-install script execution |
| Lockfile Immutability | PI_ALLOW_LOCKFILE_CHANGE pre-commit gate |
Prevents un-audited transitive dependency drift |
| Strip-Only TypeScript | Erasable Node syntax | No un-audited JS emit transformers |
For full details, review SECURITY.md, docs/COMPLIANCE.md, and docs/SECURITY_AND_AIRGAP.md.
Q: Does LUMI transmit codebase telemetry or code snippets to external servers?
No. LUMI executes entirely client-side on your host machine or micro-VM container. Code snippets are sent only directly to the AI provider endpoint configured by the user. When running via Ollama or local gateways, zero network calls leave your local machine.
Q: How do I run LUMI behind an enterprise proxy?
Set standard
HTTP_PROXY / HTTPS_PROXY environment variables in your terminal shell, or configure a custom base URL endpoint inside custom provider extensions.
Q: What happens if an AI provider API endpoint times out?
LUMI's multi-provider router automatically captures provider connection errors and prompts for secondary fallback routing without losing active session state.
For detailed error triage and common pitfalls, check TROUBLESHOOTING.md.
LUMI is built by an open community of engineers dedicated to deterministic, high-performance AI tooling:
- DEVELOPMENT.md: Engine developer field guide & inner-loop setup.
- CONTRIBUTING.md: Contributor quality gates, triage process, and code standards.
- GOVERNANCE.md: Open source project governance, RFC lifecycle, and maintainers.
- SUPPORT.md: Support channels, Discord community, and enterprise SLA escalation.
- CODE_OF_CONDUCT.md: Community charter & expectations.
- SECURITY.md: Responsible vulnerability disclosure policy.
Before submitting pull requests or committing code, run the verification suite:
# Full monorepo check (formatting, types, imports, shrinkwrap, browser smoke)
npm run check
# Run non-e2e test suite from repository root
./test.sh
# Run specific package tests (e.g., coding-agent suite)
node node_modules/vitest/dist/cli.js --run packages/coding-agent/test/suite/harness.ts- Erasable TypeScript Syntax: Code must conform to Node strip-only mode (no
enum,namespace, parameter properties, or non-standard TS emit features). - Zero-GC Compliance: Substrate paths in
broccolidbmust use pre-allocated buffers and avoid allocations inside hot loops. - Top-Level Imports Only: Dynamic inline imports (
await import(...)) are prohibited.
This repository contains components under different licenses:
- Codemarie (
packages/codemarie/) and BroccoliDB (packages/broccolidb/) are licensed under the Apache License 2.0. - Pi packages (
packages/agent/,packages/ai/,packages/client/,packages/coding-agent/,packages/evals/,packages/protocol/,packages/server/,packages/session-backends/,packages/telemetry/,packages/tui/) and original Pi files are licensed under the MIT License.
