Lemon

Lemon is a resilient, BEAM-native personal AI assistant and agent platform. Built on Elixir/OTP, it provides supervised per-run agent processes, multi-channel messaging, pluggable execution engines, persistent memory, and deterministic simulation arenas.

---

Why Lemon?

• Multi-channel and always on — Chat with your agent across Telegram, Discord, WhatsApp, XMTP, the terminal TUI, or the Web UI.
• Model-agnostic — Connect to 27 configured LLM providers, including Anthropic, OpenAI, Google Gemini, Bedrock, Azure, and OpenAI-compatible services. Lemon provides unified streaming, automatic retries, rate limiting, and cost accounting (lemon_ai); compatible local endpoints can be configured separately.
• Coding agent and MCP — Native tool execution, MCP (Model Context Protocol) client/server bridge, subagent orchestration, browser automation, LSP integration, and CLI engines for Claude Code, Codex, Kimi, OpenCode, and Pi.
• Durable memory — SQLite-backed full-text recall, document ingestion, and a provider interface for optional semantic backends, including Honcho long-term memory integration (lemon_memory).
• LemonSim and benchmark arenas — Event-sourced simulation worlds (Werewolf, Space Station, Stock Market, Survivor, Poker) and reproducible offline benchmark scoring without provider API keys.
• Supervised on the BEAM — Each agent run is an isolated OTP process. Separate conversations execute concurrently, crashed workers are supervised, and durable session state survives individual requests.

Design: Agents Are a Concurrency Problem and BEAM Agent Architecture.

---

Quickstart

1. Install Lemon

Install the prebuilt binary runtime directly into ~/.lemon/bin:

curl -fsSL https://raw.githubusercontent.com/z80dev/lemon/main/install.sh | sh

(Add ~/.lemon/bin or $HOME/.lemon/bin to your PATH if prompted.)

2. Configure Providers & Models

Run the interactive setup wizard to configure your preferred LLM provider and API keys:

lemon setup

Verify your setup with the diagnostic doctor:

lemon doctor

3. Start Chatting

Launch the interactive Terminal UI (TUI):

lemon

---

Connect Messaging Channels

Connect Lemon to your favorite chat platforms:

Telegram

lemon gateway setup telegram

Discord

lemon gateway setup discord

Script & CI Notifications

Send messages or upload build artifacts directly to your channels from shell scripts or CI pipelines:

# Installed runtime (use ./bin/lemon in a source checkout)
lemon send --to telegram:<chat_id> "Deployment complete"

# Send an alert with attachments
lemon send --to discord:#ops --attach release-notes.md --attach build.log "Build finished"

(See Script Notifications Reference for delivery options and default target configuration.)

---

Source Development

For development or contributing to Lemon, clone the repository and build from source:

Prerequisites

• Erlang/OTP 28.5+ & Elixir 1.19.5+
• Bun 1.3.14+ (for TUI development)
• Node.js 24 LTS+ (for Web UI development)

Build & Run

# Clone the repository
git clone https://github.com/z80dev/lemon.git
cd lemon

# Fetch dependencies & compile
mix local.hex --force
mix deps.get
mix compile

# Run initial setup & doctor
./bin/lemon setup
./bin/lemon doctor

# Launch the dev TUI client
./bin/lemon-tui

---

LemonSim and Simulation Arenas

Lemon includes LemonSim, an event-sourced simulation engine and arena system for benchmarking model behavior deterministically.

You can run deterministic simulations locally without any API keys:

# Run offline Tic-Tac-Toe
mix lemon.sim.tic_tac_toe --offline-strategy random --seed 42 --no-persist --max-turns 10

# Run VendingBench benchmark preset
mix lemon.sim.vending_bench --preset ci --offline-strategy baseline --sim-id vb_ci

# Verify and score the game artifact
mix lemon.sim.verify apps/lemon_sim/priv/game_logs/vending_bench/vb_ci
mix lemon.sim.score  apps/lemon_sim/priv/game_logs/vending_bench/vb_ci

Learn more in the LemonSim Guide and Benchmark Guides.

---

Architecture

Lemon is organized as an Elixir umbrella split into 9 modular core packages, a reference runtime, and product applications.

Core Packages

Package	Role & Contents
lemon_ai	Provider-agnostic LLM client (27 configured providers), streaming API, rate limiting, circuit breaker, cost tracking
lemon_core	Shared bus, Event envelopes, Store (ETS/JSONL/SQLite), encrypted secrets, config management
lemon_agent	Core agentic loop, tool registry, subagents, and model runtime
lemon_memory	SQLite full-text search, memory provider registry, document ingestion pipeline, session search
lemon_media	Redacted-by-construction media job records, hashing, and audio/image processing
lemon_router	Message routing, run lifecycle (single-flight execution, queue/steer/coalesce), session orchestration
lemon_gateway	Engine execution runtime, scheduler, locks, and ingress transports
lemon_channels	Channel core, Plugin behaviour, Telegram/Discord/WhatsApp/XMTP adapters, outbox & presentation
lemon_platform_test	Contract-test kit (BackendCase, PluginCase, EngineCase, ProviderCase) for platform extensions

Reference Runtime & Products

• Reference Runtime (in-repo): lemon_control_plane (JSON-RPC API), lemon_cli, lemon_cli_runners (vendor CLI engines), lemon_web, lemon_automation, lemon_skills, lemon_browser, lemon_lsp.
• Products: coding_agent, coding_agent_ui, lemon_mcp, lemon_sim, lemon_sim_ui, lemon_tcg, lemon_evals.
• Satellites: x_api (self-registering X / Twitter integration).

Dependency Graph

Dependencies flow strictly downward. Core platform packages never depend on products or reference runtimes. The published-package edges below are complete; consumption edges from the reference runtime, products, and satellites are representative:

%% Source of truth: apps/*/mix.exs in_umbrella deps (see docs/architecture_boundaries.md).
%% Solid = compile-time dependency. Dashed = runtime-only seam (no compile edge).
graph TD
    subgraph published["Published packages · Hex (the nine)"]
        core["lemon_core"]
        ai["lemon_ai"]
        agent["lemon_agent"]
        mem["lemon_memory"]
        media["lemon_media"]
        chan["lemon_channels"]
        router["lemon_router"]
        gw["lemon_gateway"]
        kit["lemon_platform_test"]
    end

    subgraph reference["Reference runtime · in-repo, unpublished"]
        cp["lemon_control_plane"]
        cli["lemon_cli"]
        web["lemon_web"]
        auto["lemon_automation"]
        skills["lemon_skills"]
        browser["lemon_browser"]
        lsp["lemon_lsp"]
    end

    subgraph products["Products · consume the packages as a third party would"]
        ca["coding_agent"]
        caui["coding_agent_ui"]
        mcp["lemon_mcp"]
        evals["lemon_evals"]
        sim["lemon_sim"]
        simui["lemon_sim_ui"]
        tcg["lemon_tcg"]
    end

    subgraph satellite["Satellite · self-registering vendor integration"]
        xapi["x_api"]
    end

    %% Published-tier compile edges
    agent --> ai
    agent --> core
    mem --> core
    media --> core
    chan --> core
    chan --> agent
    chan --> media
    router --> core
    router --> ai
    router --> agent
    router --> mem
    router --> media
    gw --> core
    gw --> agent
    kit --> core
    kit --> agent
    kit --> ai
    kit --> chan
    kit --> gw
    kit --> mem

    %% The one allowed router->channels compile edge
    router -->|"facade"| chan

    %% Runtime-only seams
    chan -.->|"LemonCore.RouterBridge"| router
    router -.->|"LemonCore.EngineRuntime behaviour"| gw

    %% Representative one-way consumption into the platform
    cp --> router
    ca --> gw
    xapi -.->|"self-registers at boot"| chan

---

Engineering Guarantees

• Compiler-Enforced Boundaries — AST-level architecture verification (architecture_rules_check.ex) ensures no layer violations or circular dependencies exist.
• Contract Testing for Extensions — lemon_platform_test ships compliance case templates so third-party channel adapters, memory backends, and engines can verify their implementations safely.
• Typed, Reader-Owned Configuration — Over 260 environment variable declarations are defined directly by their consumer modules (config/config.exs).
• Deterministic Test Suites — Fast, isolated ExUnit test execution with network scrubbing and temp dir sandboxing (scripts/test).
• Continuous Security Audits — OSV-Scanner checks the listed Elixir and JavaScript lockfiles when dependency manifests change and on a weekly schedule (osv-scanner.yml).

---

Documentation

Guide	Description
Documentation Index	Complete documentation catalog
Installation Guide	Prebuilt releases, platform support, and headless setup
Configuration Reference	Runtime configuration and environment variables
Testing Guide	Test suites, quality gates, and CI parity
Mix Tasks Reference	Grouped reference for all mix lemon.* commands
Skills Documentation	Skill registry, discovery, and custom assistant tools
Platform Split Plan	Architecture evolution and package decoupling roadmap
Benchmark Guides	Running model benchmarks in LemonSim

---

Development and Quality Commands

# Fast test suite (compilation warnings as errors + ExUnit)
scripts/test fast

# Full quality suite (Credo, doc freshness, architecture boundaries)
scripts/test quality

# Test specific path
scripts/test path apps/lemon_core/test

---

Contributing

We welcome contributions! Please see:

• CONTRIBUTING.md — Guidelines for human contributors.
• AGENTS.md — Working agreements for agent and automated contributors.
• SECURITY.md — Security policy and vulnerability disclosure.

---

License

Lemon is open source software licensed under the MIT License.

---

Acknowledgments

Heavily inspired by pi (Mario Zechner), with architectural ideas from Oh-My-Pi, takopi, OpenClaw, and Ironclaw. The skill library was bootstrapped from Hermes Agent. Built with Elixir on the Erlang BEAM; the TUI is powered by @oh-my-pi/pi-tui.

Named after a very good cat.