📌 Table of Contents

• Overview & The 3 Pillars
• Proven Token Savings & Cache Alignment
• Single-Step Installation
• The Unified Workflow
• CLI Usage Guide
  • lcc intake — Prompt Intake & Triage
  • lcc optimize — Direct Context Optimization
  • lcc inspect — Read-Only Diagnostic Inspection
  • lcc agent — Local LLM Agents (Gemma 4 e4b & Qwen3.5-4B)
  • lcc route — Hybrid Local/Cloud Routing
  • lcc compact — Instant Relevance Compaction
• Programmatic Library API Usage
  • Python API
  • TypeScript / Node.js API
• 2026 Context Engineering Templates
• Architectural Boundaries & ADRs
• Running Tests & Validation
• Built by LookADev
• License

🏛️ Overview & The 3 Pillars

lcc (Local Context Compiler) is a unified toolkit engineered for production AI workflows across CLI, Python, and TypeScript/Node.js. It operates around three permanent, decoupled pillars:

flowchart LR
  subgraph P1["1. Deterministic Core"]
    direction TB
    C1["Boilerplate cleaning"]
    C2["Paragraph deduplication"]
    C3["Exact/approx token budget"]
  end

  subgraph P2["2. Intelligent Intake"]
    direction TB
    I1["Readiness classification"]
    I2["Intent & brief structuring"]
    I3["Clarifying questions generation"]
  end

  subgraph P3["3. Local Agents & Router"]
    direction TB
    A1["Gemma 4 e4b (0 remote tokens)"]
    A2["Qwen3.5-4B (ChatML / JSON)"]
    A3["Conservative verifier gates"]
    A4["Cloud escalation (Fireworks AI)"]
  end

  RawInput["Raw Context / Audio / Prompt"] --> P2
  P2 --> P1
  P1 --> P3
  P3 --> FinalOutput["Final Answer + Token Accounting Report"]

1. Deterministic Context Engine Core (lcc.cleaning, lcc.token_budget, lcc.inspection, lcc.pipeline): 100% deterministic, local-first context optimization with zero network requests and zero LLMs inside the core.
2. Intelligent Prompt Intake & Triage (lcc.intake): Analyzes messy audio transcripts, voice notes, and rambling prompts, assigning operational readiness status (READY_TO_EXECUTE, NEEDS_LIGHT_REFINEMENT, NEEDS_INTAKE, BLOCKED).
3. Local Agents & Hybrid Router (lcc.agents, lcc.router): Runs edge-quantized local LLMs (Gemma 4 e4b and Qwen3.5-4B) with 0 remote tokens, verifying candidate quality before selective escalation to frontier cloud models.

📊 Proven Token Savings & Cache Alignment

📦 Single-Step Installation

1. Python CLI & Library (Includes LCC Core + Intake + Local Agents)

Requires Python 3.11+.

# Standard installation
pip install local-context-compiler

# Install with exact tokenizer support (tiktoken)
pip install "local-context-compiler[tiktoken]"

# Or install globally as a CLI tool with pipx
pipx install "local-context-compiler[tiktoken]"

Install from Source / Local Repository

git clone https://github.com/lucasmartins-ai/lcc.git
cd lcc

# Install in editable mode with development tools
pip install -e ".[dev,tiktoken]"

2. Node.js / TypeScript Package

Requires Node.js 18+.

npm install local-context-compiler
# or
pnpm add local-context-compiler
# or
yarn add local-context-compiler

Verify your installation:

lcc --version
lcc --help

🔄 The Unified Workflow

[Raw Input / Voice Note / Context Dump]
                  │
                  ▼
       [1. lcc intake Triage] ──► Classify Readiness & Extract Structured Operational Brief
                  │
                  ▼
     [2. lcc Local Compilation] ──► Strip Boilerplate, Deduplicate Chunks, Count Tokens
                  │
                  ▼
      [3. KV-Cache Alignment]  ──► Render Contract Template (Claude XML / Code Agent / Markdown)
                  │
                  ▼
     [4. Hybrid Local Routing] ──► Local Agent (Gemma 4 e4b / Qwen3.5-4B) with Quality Verifier
                  │
       ┌──────────┴──────────┐
       ▼                     ▼
[0 Remote Tokens]    [Cloud Escalation]
(Local Accept)       (Fireworks AI / Claude / GPT)

🖥️ CLI Usage Guide

1. lcc intake — Prompt Intake & Triage

Processes raw text or voice transcripts, analyzes ambiguity, extracts missing requirements, and compiles the formatted prompt:

# Run intake on a raw file with Claude XML contract formatting
lcc intake draft_prompt.txt --model claude-sonnet-5 --template claude_xml

# Run intake directly from a natural language string
lcc intake "Maybe we should refactor something with the database, not sure" --model gemini-3.6-flash

# Output structured JSON intake report alongside the compiled prompt
lcc intake notes.txt --report intake_report.json --output compiled_prompt.md

2. lcc optimize — Direct Context Optimization

Deduplicates and cleans boilerplate from context files deterministically:

lcc optimize context.txt \
  --question "Identify performance bottlenecks" \
  --template code_agent \
  --model gpt-5.6-terra \
  --output optimized_prompt.md

3. lcc inspect — Read-Only Diagnostic Inspection

Inspects token counts, boilerplate ratio, and projected cost savings without altering source files:

lcc inspect large_context.txt --model claude-sonnet-5

4. lcc agent — Local LLM Agents (Gemma 4 e4b & Qwen3.5-4B)

Directly execute or diagnose local agent backends with 0 remote tokens used:

# Check local agent connectivity and health
lcc agent health

# Run text generation directly on Gemma 4 e4b
lcc agent run --prompt "Summarize token budget policies" --model gemma-4-e4b

# Run strict JSON generation on Qwen3.5-4B
lcc agent run --prompt "Extract status: ready, code: 200" --model qwen3.5-4b --format json

5. lcc route — Hybrid Local/Cloud Routing

Execute policy-driven hybrid routing and run benchmark evaluation suites:

# Run hybrid routing on a task fixture
lcc route run --task examples/tasks/noisy_context.json

# Run evaluation suite across task cases
lcc route eval --cases examples/tasks --output eval/reports/report.json

6. lcc compact — Instant Relevance Compaction (opt-in, cache-aware)

Drop context blocks that are irrelevant to an objective before any large model sees them. Narrow model judgment (TypeSafe System One / Jev) scores blocks in batched calls sent concurrently (~0.7s per call for up to 8 blocks); without an API key it falls back to a fully local mechanical pass. Blocks end in one of three states: keep (bytes re-emitted exactly), trim (a bounded head plus an audit note — the middle gear between keep and drop), or drop. Provider failures never drop content, and sticky decisions keep the output byte-stable so prompt/KV caches survive.

# Full pass (Jev-scored): drops noise, keeps an auditable decision trail
lcc compact dossier.md -q "reduce mobile booking friction" -o compacted.md -r report.json

# Cache-safe incremental pattern for live sessions (never touch the newest blocks)
lcc compact dossier.md -q "reduce mobile booking friction" \
  --prefix-marker "<!-- lcc:cache-break -->" \
  --preserve-tail 6 \
  --decisions-cache ~/.cache/lcc/decisions.jsonl

# Strict keep/drop, no middle gear
lcc compact dossier.md -q "reduce mobile booking friction" --trim-head-chars 0

# Fully offline (mechanical): drops only zero-lexical-overlap blocks
lcc compact dossier.md -q "reduce mobile booking friction" --provider mechanical

The relevance-compaction-1.1 report exposes per-block scores and decisions (including chars_after for trimmed blocks) plus cache-accounting fields (first_mutation_offset, prefix_sha256, output_sha256, reused_decisions) and reduction accounting (reduction_ratio, worth_it, min_reduction). See docs/CACHE_ALIGNMENT.md for the cost math and the epoch discipline (ADR 0013).

🚀 Programmatic Library API Usage

Python API

from lcc import LccIntake, LccCompressor, parse_intake, process_intake
from lcc.agents import LocalAgent, LocalAgentConfig
from lcc.router import LCCRouter, TaskInput

# 1. Quick all-in-one Intake & Context Compilation
result = process_intake(
    "Rewrite authentication logic. Sent from my iPhone",
    model="claude-sonnet-5",
    template="claude_xml"
)

print("Readiness:", result.parsed.readiness.value)       # READY_TO_EXECUTE
print("Readiness Score:", result.parsed.readiness_score) # 90/100
print("Formatted Prompt:\n", result.formatted_prompt)

# 2. Direct LCC Context Compression
compressor = LccCompressor(model="claude-sonnet-5", max_tokens=2000)
comp_res = compressor.compress("Raw context text...")
print("Tokens Saved:", comp_res.saved_tokens)

# 3. Direct Local Agent Execution (0 Remote Tokens)
agent = LocalAgent(LocalAgentConfig(backend="ollama", model_name="gemma-4-e4b"))
answer = agent.solve(TaskInput(task_id="t1", instruction="Summarize runbook"))
print(answer.answer)

TypeScript / Node.js API

import { LccIntake, LccCompressor, parseIntake, processIntake } from 'local-context-compiler';

// 1. Unified Prompt Intake Pipeline
const intake = new LccIntake({
  model: 'claude-sonnet-5',
  template: 'claude_xml'
});

const result = intake.process(
  "Maybe we need to update the API endpoints. Sent from my iPhone"
);

console.log(`Status: ${result.parsed.readiness}`); // NEEDS_INTAKE
console.log(`Questions:`, result.parsed.questions);
console.log(result.formattedPrompt);

// 2. Direct Context Compression
const compressor = new LccCompressor({ model: 'gpt-5.6-terra' });
const compressed = compressor.compress("Raw context...");
console.log(`Saved: ${compressed.savingsPercentage}%`);

🎨 2026 Context Engineering Templates

🏛️ Architectural Boundaries & ADRs

lcc is engineered around strict architectural boundaries:

• Deterministic Core & Model-Assistance Boundary: src/lcc/ is model-free, offline, and deterministic. Optional model assistance stays strictly outside the deterministic core and inspection boundaries (ADR 0010).
• Offline Network Guard: lcc blocks runtime network requests by default via a tightly scoped guard (ADR 0008).
• Inspection Boundary: lcc inspect is strictly diagnostic and transformative-free (ADR 0009).
• Semantic Retrieval Boundary: Phase 2 boundary status scaffold (ADR 0011).

🧪 Running Tests & Validation

Run all test suites for Python and Node.js:

# Python test suite (283+ unit tests)
pytest

# Node.js test suite
node test/index.test.js

# Documentation & ADR integrity checks
pytest tests/test_docs.py

⭐ Star & Support

If lcc saves you tokens and API expenses:

• ⭐ Star this repository on GitHub!
• 🍴 Fork & Integrate into your AI agent pipelines.

Built by LookADev

lcc is built and maintained by LookADev, a high-performance software & AI automation studio. We use deterministic context engineering in production to cut token costs and maintain repeatable agent workflows.

Start a project → lookadev.com · Email: [email protected]

📄 License

Open-source software licensed under the MIT License.