lea

Lea

Structural reasoning engine for AI-native software engineering.

Lea transforms repositories into deterministic structural graphs — enabling AI agents and developers to reason about architecture, dependencies, execution flow, and system impact with minimal context and maximum precision.

---

Lynx discovers. Lea reasons.

Vision • Features • Architecture • Installation • Quick Start • Command Guide • Roadmap • Contributing

The Vision

Modern AI coding systems suffer from context window limitations, token inflation, and "context entropy." Most rely on probabilistic semantic chunking (embeddings), which often loses the architectural "big picture."

Software is symbolic, not just semantic. lea focuses on:

1. Structural Retrieval First: Symbols, dependencies, call graphs, and architectural boundaries.
2. Semantic Retrieval Second: Natural language understanding on top of structural certainty.

Key Features

• Multi-Language AST Indexing: Native support for Go (go/ast) and Python, TypeScript, and Rust via Tree-sitter.
• Structural Graph Engine: Models your codebase as a graph of functions, structs, interfaces, and their relationships (CALLS, IMPLEMENTS, USES).
• AI Context Compiler: Generates high-signal, markdown-optimized context for LLMs (Claude, GPT, Gemini) using deterministic retrieval with token-budget awareness.
• Model Context Protocol (MCP): Expose your codebase structure directly to AI agents via a standardized protocol.
• Blast Radius Analysis: Recursively trace incoming dependencies to determine the full impact of a code change, including direct/indirect callers, interfaces, and tests.
• Symbol Discovery: Official symbol registry for discovering available functions, structs, interfaces, and packages without manual grep.
• Architectural Guardrails: Define and enforce architectural boundaries using an explicit Allow/Deny rule engine.
• Workspace Metadata & Agent Export: Automatically generate deterministic repository metadata (WORKSPACE.md) and reasoning protocols (AGENT.md, .agent-manifesto.md) to teach AI agents how to navigate your codebase structurally.
• Interactive TUI: A rich, terminal-based explorer for fuzzy symbol navigation and dependency browsing.
• Control Flow & Architecture: Trace execution paths and detect boundary violations against architectural constraints.
• Cross-Package Resolution: Full support for repository-wide symbol resolution, including internal module calls and external package dependencies.
• Incremental & Reactive: Real-time graph updates using fsnotify without re-indexing the entire repository.

Architecture

lea is built with a modular, performance-oriented architecture designed for local execution:

• Parser Layer: Pluggable parsers using native ASTs and Tree-sitter for high-fidelity symbol extraction.
• Graph Engine: A high-performance relationship model that treats your codebase as a first-class graph.
• Storage Layer: SQLite-backed storage utilizing recursive CTEs for complex graph traversals.
• Integration Layer: Built-in MCP server for AI agents and a Bubble Tea-powered TUI for humans.

       ┌────────────────────────────────────────────────────────┐
       │                 Local Filesystem Event                 │
       └───────────────────────────┬────────────────────────────┘
                                   │ (fsnotify)
                                   ▼
       ┌────────────────────────────────────────────────────────┐
       │ Incremental Parser Layer (Native Go AST / Tree-sitter) │
       └───────────────────────────┬────────────────────────────┘
                                   │ (Extracted Symbols)
                                   ▼
       ┌────────────────────────────────────────────────────────┐
       │   Storage Layer: SQLite Graph Engine (Recursive CTEs)  │
       └───────────────────────────┬────────────────────────────┘
                                   │
                    ┌──────────────┴──────────────┐
                    ▼                             ▼
       ┌────────────────────────┐    ┌──────────────────────────┐
       │   Integration Layer    │    │     Retrieval Engine     │
       │   (Bubble Tea TUI)     │    │   (MCP Server for AIs)   │
       └────────────────────────┘    └──────────────────────────┘

Installation

Go Install

go install github.com/PizenLabs/lea/cmd/lea@latest

Install Script (curl)

curl -fsSL https://raw.githubusercontent.com/PizenLabs/lea/main/scripts/install.sh | bash

Homebrew (Tap)

brew tap PizenLabs/tap
brew install lea

From Source

# Clone the repository
git clone https://github.com/PizenLabs/lea.git
cd lea

# Build the binary
make build

# Install to your GOPATH/bin
make install

Check Your Version

lea version

Quick Start

1. Index your project

Initialize the structural graph for your repository.

lea index .

2. Start the MCP Server

Connect your favorite AI agent (like Claude Code or Aider) directly to your codebase.

lea mcp

3. AI-Native Integration

Generate metadata and export instructions for your AI agents (Claude, Cursor, Gemini, etc.).

# Generate structural metadata and reasoning protocols
lea index .

# Export configurations for specific agents
lea export claude
lea export cursor
lea export gemini

4. Interactive Exploration

Usage Guide

For a deeper walkthrough (installation, workflows, and diagrams), see GUIDE.md.

Usage Patterns

AI-Agent Workflow (MCP)

1. Find the target symbol to get exact file and symbol coordinates.
2. Expand context to pull immediate neighbors (CALLS, USES, IMPLEMENTS).
3. Trace execution to map the ordered call graph for the change.
4. Check boundaries against architecture rules before committing updates.

Developer Workflow (CLI/TUI)

• Use lea tui for fuzzy symbol search and graph browsing.
• Use lea context to generate prompt-ready context for web LLMs.
• Use lea flow and lea trace to understand execution order and impact.

AI Agent Integration (Export)

Lea bridges the gap between raw source code and AI reasoning by providing deterministic integration points:

• WORKSPACE.md: Repository statistics and facts generated by lea index.
• AGENT.md: A recommended structural reasoning protocol for all AI agents.
• Export Targets: Use lea export <target> to generate CLAUDE.md, .cursorrules, GEMINI.md, and more.

Command Guide

Additional Diagrams

MCP Query Flow

sequenceDiagram
    autonumber
    actor Agent as AI Agent
    participant Lea as lea (MCP Server)
    participant DB as SQLite (Graph Engine)

    Agent->>Lea: find_symbol(name)
    Lea->>DB: Query exact Symbol URI/File
    DB-->>Lea: Return Node
    Lea-->>Agent: Return Symbol Coordinates

    Agent->>Lea: get_neighbors(URI)
    Lea->>DB: Traverse Edges (CALLS, USES, etc.)
    DB-->>Lea: Return Subgraph
    Lea-->>Agent: Return Markdown Context

Incremental Indexing Loop

[Filesystem Event: Modify/Create/Delete]
                   │
                   ▼
       ┌───────────────────────┐
       │   Debounce & Batch    │ (Gathers changes over 100-300ms)
       └───────────┬───────────┘
                   │
                   ▼
       ┌───────────────────────┐
       │   Invalidation Stage  │ (Deletes affected Nodes & Edges in SQLite)
       └───────────┬───────────┘
                   │
                   ▼
       ┌───────────────────────┐
       │  Incremental Parsing  │ (Native go/ast or Tree-sitter AST extraction)
       └───────────┬───────────┘
                   │
                   ▼
       ┌───────────────────────┐
       │     Graph Commit      │ (Atomic SQL Transaction: Inserts new entities)
       └───────────────────────┘

Troubleshooting

• If the graph is empty, re-run lea index . and confirm your repository path is correct.
• For architecture checks, ensure your rules file (for example arch.yaml) is present and valid.
• If symbols are missing, confirm the target language parser is supported and available.

Roadmap

• Phase 1: MVP: Go parser, SQLite storage, basic graph queries.
• Phase 2: AI Context Layer: High-signal markdown generation and context compilation.
• Phase 3: Incremental Updates: Real-time file watching and partial re-indexing.
• Phase 4: MCP Integration: Standardized protocol for AI agent connectivity.
• Phase 5: Interactive TUI: Fuzzy navigation and visual dependency exploration.
• Phase 6: Multi-Language Support: Tree-sitter integration for Python, Rust, and TypeScript.
• Phase 7: Advanced Retrieval: Control flow, architecture guardrails, and blast radius.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines on development, testing, and pull requests.

License

lea is licensed under the MIT License.

Built for the future of AI-native engineering. 🦾