Lemon is an AI coding assistant that runs on your own machine, built as a distributed system of concurrent processes on the BEAM (Erlang VM). You talk to it via Telegram while it runs locally — or use the terminal UI or web UI directly.
Named after a very good cat.
- Elixir 1.19+ and Erlang/OTP 27+
- A model provider API key (Anthropic, OpenAI, etc.)
- Node.js 20+ (TUI/Web clients only)
git clone https://github.com/z80dev/lemon.git
cd lemon
mix deps.get
mix compileCreate ~/.lemon/config.toml:
[providers.anthropic]
api_key_secret = "llm_anthropic_api_key"
[defaults]
provider = "anthropic"
model = "anthropic:claude-sonnet-4-20250514"
engine = "lemon"Store your API key:
mix lemon.setup secrets set llm_anthropic_api_key "sk-ant-..."mix lemon.setup # interactive walkthrough
mix lemon.doctor # verify everything is workingTUI (development/local):
./bin/lemon-dev /path/to/your/projectTelegram gateway:
./bin/lemon-gateway- Create a bot via
@BotFather— run/newbot, copy the token - Add to config:
gateway.telegram.bot_token = "..."andallowed_chat_ids = [your_id] - Restart the gateway, then message your bot
Full Telegram setup details: docs/user-guide/setup.md
| Feature | How |
|---|---|
| Chat with an AI coding assistant | Telegram, TUI, or Web UI |
| Run tasks in a specific repo | /new /path/to/repo or bind a project in config |
| Use skills (reusable knowledge modules) | mix lemon.skill list / install / inspect |
| Search past runs by content | search_memory tool (enable session_search flag) |
| Generate skill drafts from memory | mix lemon.skill draft generate |
| Schedule recurring tasks | Cron configuration in ~/.lemon/config.toml |
| Use multiple LLM providers | 26 providers supported; configure in [providers] |
| Command | What it does |
|---|---|
/new |
Start a new session |
/new /path/to/repo |
Start session bound to a repo |
/cwd [path|clear] |
Set working directory for this chat |
/resume |
List previous sessions |
/cancel |
Cancel a running run |
/lemon, /claude, /codex |
Switch engine for one message |
/steer, /followup, /interrupt |
Queue mode overrides |
Agent:
- 20 built-in tools:
bash,read,write,edit,grep,websearch,webfetch,task,agent, and more - Real-time streaming with live steering (inject messages mid-run)
- Session persistence via JSONL with tree-structured history
- Context compaction and branch summarization
Routing & Execution:
- Lane-aware scheduling: main (4), subagent (8), background (2)
- 26 LLM providers with automatic model selection
- Multi-engine: native Lemon + Codex CLI, Claude CLI, OpenCode CLI, Pi CLI
- Adaptive routing: learns from past run outcomes (enable
routing_feedback)
Skills:
- Reusable knowledge modules loaded by the agent when relevant
- Manifest v2 format with category, required tools, and structured body
- Automatic draft synthesis from successful runs (enable
skill_synthesis_drafts)
Infrastructure:
- Telegram, Discord, X/Twitter channel adapters
- Cron scheduling with heartbeats
- Event-driven architecture with pub/sub across all components
- Encrypted secrets keychain
| Audience | Start here |
|---|---|
| New users | docs/user-guide/setup.md — full setup walkthrough |
| Skills | docs/user-guide/skills.md — listing, installing, synthesizing |
| Memory & search | docs/user-guide/memory.md — session search, retention |
| Adaptive features | docs/user-guide/adaptive.md — routing feedback, synthesis |
| Architecture | docs/architecture/overview.md — system design |
| Config reference | docs/config.md — full TOML reference |
| Non-Elixir users | docs/for-dummies/README.md — plain-English tour |
| Contributors | AGENTS.md — project navigation and conventions |
| Full docs index | docs/README.md — complete documentation map |
mix test # all tests
mix test apps/lemon_skills # one app
mix lemon.quality # lint + doc freshness + architecture boundariesRelease profiles:
| Profile | Use case |
|---|---|
lemon_runtime_min |
Headless / CI / embedded |
lemon_runtime_full |
Local development |
games_platform |
Public games web deployment |
sim_broadcast_platform |
Public sim broadcast deployment (lemon_sim_ui) |
MIX_ENV=prod mix release lemon_runtime_full
MIX_ENV=prod mix release sim_broadcast_platformSee ROADMAP.md for what's planned.
MIT — see LICENSE file.
Lemon is heavily inspired by pi (Mario Zechner), draws architectural ideas from Oh-My-Pi (can1357), takopi (banteg), OpenClaw, and Ironclaw. Skill library bootstrapped from Hermes Agent (Nous Research).
Built with Elixir and the BEAM. TUI powered by @mariozechner/pi-tui.