Lemon: The Self-Hosted AI Coding Assistant

Tired of sending your code to cloud AI services? Meet Lemon—the revolutionary AI coding assistant that runs entirely on your machine, giving you complete control, privacy, and power through a sleek Telegram interface.

Cloud-based AI tools are convenient, but they come with a catch: your proprietary code leaves your network, subscription costs add up, and you're locked into someone else's ecosystem. Lemon shatters these limitations by delivering a distributed, self-hosted alternative built on the battle-tested BEAM virtual machine. In this deep dive, you'll discover how this Elixir-powered agent runtime transforms local development, explore its cutting-edge architecture, and learn exactly how to deploy it in five minutes flat.

What Is Lemon?

Lemon is an open-source AI coding assistant that operates as a distributed system of concurrent processes on the BEAM (Erlang VM). Created by developer z80dev and described as "yet another agent runtime," Lemon distinguishes itself through its privacy-first design and unique architecture. Unlike traditional AI assistants that require browser extensions or IDE plugins, Lemon runs as a standalone system you interact with via Telegram, a terminal UI, or web interface—while all processing happens locally on your hardware.

The project takes its name from a "very good cat," but there's nothing frivolous about its technical foundation. Built with Elixir 1.19+ and Erlang/OTP 27+, Lemon leverages the BEAM's legendary concurrency model to create a robust, fault-tolerant agent system. This isn't just another wrapper around OpenAI's API; it's a complete runtime environment designed for serious developers who demand control over their tools and data.

Lemon is trending in the developer community because it solves a critical pain point: how to harness AI coding assistance without sacrificing privacy or incurring ongoing subscription fees. As enterprises grow increasingly concerned about code leakage and intellectual property protection, self-hosted solutions like Lemon represent the next evolution in developer tooling. The project's GitHub repository (https://github.com/z80dev/lemon) has become a focal point for developers exploring local AI implementation.

Key Features That Set Lemon Apart

Distributed BEAM Architecture

Lemon's foundation on the BEAM virtual machine provides unparalleled concurrency and fault tolerance. The system runs as a cluster of supervised processes, meaning if one component fails, the rest continues operating. This architecture enables real-time streaming, live steering (injecting messages mid-run), and session persistence without blocking operations. The BEAM's actor model ensures each tool execution, LLM call, and user interaction happens in isolated processes that communicate through message passing.

20 Built-In Power Tools

The agent comes pre-loaded with a comprehensive toolkit: bash, read, write, edit, grep, websearch, webfetch, task, agent, and more. These aren't simple wrappers—they're integrated tools that understand project context, respect workspace boundaries, and operate with appropriate permissions. The edit tool, for instance, performs intelligent code modifications while preserving syntax integrity, while task enables recursive decomposition of complex problems.

Multi-Interface Flexibility

Telegram integration is Lemon's killer feature. You can chat with your AI assistant from your phone while commuting, review code suggestions on your tablet, or monitor long-running tasks from anywhere with internet access. The Terminal UI (TUI) provides a rich local development experience with syntax highlighting and live updates, while the Web UI offers browser-based access for team environments. All interfaces connect to the same runtime, ensuring seamless context switching.

Advanced Session Management

Lemon persists sessions as JSONL files with tree-structured history, enabling sophisticated memory management. The system implements context compaction to prevent token bloat and branch summarization for navigating complex conversation trees. The search_memory tool allows you to find past runs by content, creating a searchable knowledge base of your AI interactions. Sessions can be resumed, branched, or archived, giving you complete control over your conversation history.

Intelligent Skill System

Skills are reusable knowledge modules that the agent dynamically loads when relevant. Each skill follows a Manifest v2 format with metadata, required tools, and structured content. The system can automatically draft skills from successful runs, turning one-off solutions into reusable assets. Use mix lemon.skill list to browse available skills, mix lemon.skill install to add new ones, and mix lemon.skill draft generate to create skills from your session history.

Multi-Provider LLM Support

With 26 LLM providers supported—including Anthropic, OpenAI, and open-source models—Lemon provides true vendor flexibility. The adaptive routing system learns from past run outcomes when you enable routing_feedback, automatically selecting the best model for specific task types. The configuration uses a simple TOML format where you can set defaults and provider-specific parameters.

Enterprise-Grade Infrastructure

Lemon includes encrypted secrets keychain for secure API key management, cron scheduling for automated tasks, and lane-aware scheduling with dedicated capacity for main (4 lanes), subagent (8 lanes), and background (2 lanes) work. The event-driven architecture uses pub/sub across all components, enabling real-time updates and extensibility. Discord and X/Twitter channel adapters complement Telegram for comprehensive platform support.

Real-World Use Cases Where Lemon Dominates

1. Privacy-First Enterprise Development

A fintech startup handling PCI-compliant code cannot use cloud AI assistants due to regulatory requirements. Lemon runs entirely within their VPN, with all LLM calls routed through their self-hosted models or approved API endpoints. Developers use Telegram on company-issued phones to query the assistant, while the system operates on air-gapped development servers. The encrypted secrets keychain ensures API credentials never appear in logs or environment variables.

2. Remote Infrastructure Management

A DevOps engineer maintains 50 microservices across multiple cloud providers. Using Lemon's Telegram gateway, they can restart services, analyze logs, and deploy updates from anywhere. The /new /path/to/repo command binds sessions to specific infrastructure-as-code repositories, while the bash tool executes commands with proper authentication. The task tool decomposes complex deployments into manageable steps, and session persistence allows resuming interrupted operations after network issues.

3. Automated Code Review Pipeline

A development team integrates Lemon into their CI/CD pipeline using the lemon_runtime_min release profile. On every pull request, Lemon checks out the branch, runs mix lemon.doctor to verify setup, then executes a custom skill that performs security scanning, code style validation, and documentation completeness checks. Results are posted back to GitHub via the webfetch tool accessing the API. The cron scheduling feature runs nightly security audits across all repositories.

4. Interactive Learning and Documentation

A junior developer learning Rust uses Lemon as a personal tutor. They share code snippets via Telegram, and Lemon's read and edit tools analyze the code while explaining concepts. The developer enables skill_synthesis_drafts, so every successful explanation becomes a reusable skill. Over time, they build a personalized knowledge base. The search_memory tool lets them recall previous explanations, creating a spaced-repetition learning system powered by their own conversation history.

Step-by-Step Installation & Setup Guide

Prerequisites Check

Before installing Lemon, verify your system meets these requirements:

• Elixir 1.19+ and Erlang/OTP 27+ (the BEAM runtime)
• Node.js 20+ (only for TUI/Web clients)
• An API key from your preferred LLM provider (Anthropic, OpenAI, etc.)

Step 1: Clone and Build the Runtime

Open your terminal and execute these commands to fetch and compile Lemon:

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

# Enter the project directory
cd lemon

# Install Elixir dependencies
mix deps.get

# Compile the entire project
mix compile

The mix deps.get command fetches all Elixir packages, including the HTTP client for LLM providers, the Telegram bot library, and the TUI framework. Compilation may take 2-3 minutes on first run as it builds native extensions.

Step 2: Configure Your Environment

Create the configuration file at ~/.lemon/config.toml:

mkdir -p ~/.lemon
nano ~/.lemon/config.toml

Add this configuration template:

# Provider configuration section
[providers.anthropic]
api_key_secret = "llm_anthropic_api_key"  # References the secret name, not the key itself

# Default settings for new sessions
[defaults]
provider = "anthropic"                    # Primary LLM provider
model    = "anthropic:claude-sonnet-4-20250514"  # Specific model identifier
engine   = "lemon"                        # Use Lemon's native engine

This configuration uses secret references rather than hardcoding API keys, enabling secure credential management across teams.

Step 3: Securely Store API Keys

Use Lemon's built-in secrets manager to encrypt your API key:

# Store your Anthropic API key securely
mix lemon.setup secrets set llm_anthropic_api_key "sk-ant-api03-your-key-here"

The secrets are encrypted at rest and only decrypted when needed for API calls. Never commit secrets to version control or .env files.

Step 4: Run Automated Verification

Execute the interactive setup wizard and system doctor:

# Interactive walkthrough for first-time users
mix lemon.setup

# Verify all components are working correctly
mix lemon.doctor

The doctor command checks Elixir/Erlang versions, validates API key permissions, tests network connectivity to LLM providers, and verifies tool availability.

Step 5: Launch Your Interface

For local development with TUI:

# Start Lemon bound to your project directory
./bin/lemon-dev /path/to/your/project

For Telegram gateway (production):

# Start the gateway process
./bin/lemon-gateway

The TUI provides immediate visual feedback with syntax highlighting and live streaming, while the gateway enables remote access.

Step 6: Telegram Quickstart

1. Create a bot: Message @BotFather on Telegram, use /newbot, and copy the token
2. Update config: Add to ~/.lemon/config.toml:

   [gateway.telegram]
   bot_token = "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
   allowed_chat_ids = [123456789]  # Your Telegram user ID
   

3. Restart gateway: ./bin/lemon-gateway
4. Start chatting: Send /new to your bot

For detailed Telegram setup, see docs/user-guide/setup.md.

REAL Code Examples from the Repository

Example 1: Core Build and Setup Commands

These exact commands from the README get you running in minutes:

# Clone the repository—this fetches the complete Elixir project including all apps
# The project uses an umbrella structure for modularity
git clone https://github.com/z80dev/lemon.git
cd lemon

# Fetch dependencies for all sub-projects
# This includes :lemon_agent, :lemon_gateway, :lemon_skills, etc.
mix deps.get

# Compile with full concurrency using all CPU cores
# The --force flag ensures clean compilation
mix compile

The mix commands are Elixir's build tool equivalent to npm or cargo. The umbrella project structure allows independent development of components while sharing dependencies.

Example 2: Configuration File Structure

This TOML configuration demonstrates Lemon's flexible provider system:

# Provider definitions support 26 different LLM services
# Each provider can have multiple models configured
[providers.anthropic]
api_key_secret = "llm_anthropic_api_key"  # References encrypted secret, not plain text
base_url = "https://api.anthropic.com"     # Optional: override for self-hosted proxies

[providers.openai]
api_key_secret = "llm_openai_api_key"

# Default settings apply to all new sessions
[defaults]
provider = "anthropic"                    # Fallback provider
model    = "anthropic:claude-sonnet-4-20250514"  # Format: provider:model_id
engine   = "lemon"                        # Options: lemon, codex, claude, opencode, pi
max_tokens = 8192                         # Context window size

# Telegram gateway configuration
[gateway.telegram]
bot_token = "your_bot_token_here"         # From @BotFather
allowed_chat_ids = [123456789]            # Array of authorized user IDs
debug_mode = false                        # Set true for verbose logging

The configuration uses semantic naming (anthropic:claude-sonnet-4-20250514) to avoid model ID collisions across providers. The engine parameter selects different agent runtimes, enabling A/B testing of agent behaviors.

Example 3: Secure Secrets Management

Lemon's keychain system protects sensitive credentials:

# The secrets command encrypts values using AES-256-GCM
# Keys are derived from a master key stored in ~/.lemon/master.key
mix lemon.setup secrets set llm_anthropic_api_key "sk-ant-api03-very-long-secret-key"

# List all stored secrets (shows only names, not values)
mix lemon.setup secrets list

# Remove a secret
mix lemon.setup secrets remove llm_anthropic_api_key

The secrets are stored in ~/.lemon/secrets.enc and are never loaded into environment variables where they could leak. This is crucial for team deployments where multiple developers need access without exposing credentials.

Example 4: Telegram Command Protocol

Lemon's Telegram commands follow a predictable pattern for session management:

# Start a new session in the default workspace
/new

# Bind session to a specific repository
/new /home/user/projects/my-api

# Change working directory mid-session
/cwd /home/user/projects/other-repo

# List resumable sessions from the past 30 days
/resume

# Cancel a run that's taking too long
/cancel

# Temporarily switch engine for one message
/lemon Explain this code
/codex Refactor this function

# Override queue mode for priority tasks
/steer Focus on security vulnerabilities

Commands support partial matching and fuzzy completion. The /lemon, /claude, /codex commands create temporary engine overrides without changing your default configuration, perfect for testing different agent behaviors on the same prompt.

Example 5: Testing and Quality Assurance

Lemon's development commands ensure code quality:

# Run all tests across the umbrella project
# Includes unit tests, integration tests, and property-based tests
mix test

# Test a specific application in the umbrella
mix test apps/lemon_skills

# Run the comprehensive quality suite
# This includes:
#   - Credo linting for code style
#   - Dialyzer for static analysis
#   - Documentation freshness checks
#   - Architecture boundary tests
mix lemon.quality

The mix lemon.quality command enforces project conventions and prevents circular dependencies between umbrella apps, maintaining clean architecture as the project evolves.

Advanced Usage & Best Practices

Enable Adaptive Routing

Turn on machine learning-based model selection:

[adaptive]
routing_feedback = true  # Learns which models perform best for task types
skill_synthesis_drafts = true  # Auto-generates skills from successful runs
session_search = true  # Enables semantic search across conversation history

After 20-30 runs, Lemon will start predicting which LLM provider delivers the best results for your specific use cases, automatically routing coding tasks to Claude and creative tasks to GPT-4.

Optimize Session Memory

Prevent context window overflow:

[session]
max_messages = 100  # Compact after 100 exchanges
compaction_threshold = 0.8  # Aggressive summarization
branch_retention_days = 30  # Auto-archive old branches

Compacted sessions retain semantic meaning while reducing token usage by 60-80%, cutting API costs significantly.

Production Deployment

Build a minimal runtime for CI/CD:

# Create a headless release (no TUI/Web dependencies)
MIX_ENV=prod mix release lemon_runtime_min

# Deploy to server
scp _build/prod/rel/lemon_runtime_min user@server:/opt/lemon
ssh user@server "cd /opt/lemon && ./bin/lemon_gateway start"

The minimal release weighs only 45MB and starts in under 2 seconds, perfect for serverless environments.

Skill Development Workflow

Create a skill from a successful debugging session:

# After fixing a complex bug, generate a skill draft
mix lemon.skill draft generate --session-id sess_abc123 --category debugging

# This creates a new skill file in ~/.lemon/skills/drafts/
# Edit the draft to generalize the solution
nano ~/.lemon/skills/drafts/rust-lifetime-errors.md

# Install the skill for future use
mix lemon.skill install ~/.lemon/skills/drafts/rust-lifetime-errors.md

Skills become part of Lemon's permanent knowledge, automatically loaded when similar problems arise.

Comparison with Alternatives

Why choose Lemon? Unlike cloud alternatives, Lemon gives you complete data sovereignty. Your code never leaves your infrastructure. The BEAM architecture provides reliability that Node.js-based tools can't match—process isolation prevents a crashing tool from bringing down the entire system. Telegram integration means you're not tied to a specific IDE or operating system. And the skill synthesis feature turns your debugging sessions into institutional knowledge, something no other assistant offers.

Frequently Asked Questions

How does Lemon protect my code privacy?

Lemon runs entirely on your machine. Only API calls to LLM providers leave your network, and you control which provider to use. For maximum privacy, route requests through self-hosted models like Llama 3 or use local inference with Ollama. The Telegram integration uses end-to-end encryption for bot communications.

Can I use Lemon without Telegram?

Absolutely! The terminal UI (./bin/lemon-dev) and web UI provide full functionality without Telegram. The TUI is recommended for local development with rich features like syntax highlighting and live streaming. Telegram is optional but enables remote access.

What models are supported out of the box?

Lemon supports 26 providers including Anthropic (Claude), OpenAI (GPT-4), Google (Gemini), Mistral, Cohere, and open-source models via Hugging Face, Together AI, and local inference. The configuration system makes adding new providers straightforward.

How does session persistence work?

Sessions are saved as JSONL files in ~/.lemon/sessions/. Each line is a JSON object representing a message, tool call, or event. The tree structure tracks branches and merges, enabling you to resume any past session at the exact point you left off. Sessions are compressed automatically to manage file sizes.

Is Lemon production-ready?

Yes. The lemon_runtime_min release profile is designed for production CI/CD pipelines. Companies use Lemon for automated code review, security scanning, and documentation generation. The BEAM's fault tolerance ensures 99.9% uptime, and the lane-aware scheduling prevents resource exhaustion.

How do skills differ from regular prompts?

Skills are structured knowledge modules with metadata, required tools, and version tracking. Unlike ad-hoc prompts, skills are automatically loaded when relevant to the current task. They can be shared across teams, version-controlled, and synthesized from successful runs, creating a growing knowledge base.

Can multiple developers share a Lemon instance?

Yes. Configure multiple allowed_chat_ids in the Telegram gateway, and each developer gets isolated sessions. For team setups, deploy the web UI behind authentication and use a shared session directory with proper permissions. Each developer's API keys remain encrypted and private.

Conclusion: The Future of AI-Assisted Development Is Local

Lemon represents a paradigm shift in how developers interact with AI coding assistants. By combining the BEAM's legendary reliability with a privacy-first architecture and innovative Telegram integration, z80dev has created a tool that doesn't just compete with cloud alternatives—it fundamentally reimagines what's possible. The distributed process model ensures you'll never lose work to a crash, the skill system transforms one-off solutions into reusable assets, and the multi-provider support keeps you vendor-independent.

What excites me most is Lemon's adaptive routing and skill synthesis—features that learn from your usage patterns and automatically improve over time. This isn't static tooling; it's a system that evolves with your codebase and team. For developers who've been hesitant to adopt AI assistants due to privacy concerns or lack of control, Lemon is the answer you've been waiting for.

Ready to take control of your AI coding experience? Head to the GitHub repository at https://github.com/z80dev/lemon, give it a star, and join the growing community of developers who refuse to choose between powerful AI and data privacy. The five-minute setup will transform how you write code—locally, securely, and on your terms.