Lemon is a local-first AI assistant and coding-agent platform you run on your own machine. It is organized as a deliberately reduced Elixir umbrella with one canonical headless platform runtime.
The root README is intentionally short. It is the operator and quickstart entrypoint, not the full architecture book.
- Want to run Lemon locally: use the quickstart below, then read
docs/config.md. - Want to understand platform layering: read
docs/platform_tiers.mdanddocs/architecture_boundaries.md. - Want maintainer-facing navigation: start at
AGENTS.mdanddocs/README.md.
- Elixir 1.19+
- Erlang/OTP 27+
- One provider API key such as Anthropic or OpenAI
- No browser or UI runtime is required for the canonical platform
Use examples/config.example.toml as the
starting point for ~/.lemon/config.toml.
Common fields:
[defaults]for default provider, model, and engine[profiles.<id>]for assistant profiles and tool policy[gateway]for Telegram, Discord, XMTP, SMS, and voice settings[runtime]for tools, compaction, CLI runners, and budget defaults
Full reference: docs/config.md
# default platform profile
./bin/lemon
# core-only runtime
./bin/lemon --profile core| Profile | Includes |
|---|---|
core |
lemon_core, ai, coding_agent |
platform |
core plus lemon_gateway and lemon_control_plane |
Canonical membership and keep rationale live in
docs/platform_tiers.md.
| Area | Purpose |
|---|---|
apps/ |
Elixir umbrella applications |
clients/ |
TypeScript clients and browser tooling |
docs/ |
Canonical maintainer documentation hub |
bin/ |
Runtime launchers and helper scripts |
scripts/ |
Utility scripts and isolated Mix wrapper |
examples/ |
Sample config and extension stubs |
The normal runtime path is:
lemon_control_plane -> lemon_gateway -> coding_agent -> ai
Supporting concerns such as config, storage, bus, approvals, and absorbed
durable runtime state live in lemon_core.
# install deps
mix deps.get
# compile
mix compile
# full test run
mix test
# quality gates
mix lemon.quality
# isolated targeted runs
scripts/mix_isolated.sh -- compile --warnings-as-errors
scripts/mix_isolated.sh -- lemon.qualityEach app keeps its own README.md and AGENTS.md when it has meaningful local
context. Start from the root maintainer hub and then jump to the app guide you
need.