lemon 🍋

# lemon 🍋

Lemon is a local-first assistant and coding agent system (named after my cat) that you run on your own machine.

The easiest way to use Lemon day-to-day is through **Telegram**: you talk to a bot from your phone/desktop, while Lemon runs locally. Inbound/outbound messaging is handled by `lemon_channels` (Telegram adapter + outbox), runs are orchestrated by `lemon_router`, and execution is handled by `lemon_gateway` using one of the configured engines (native Lemon, Claude CLI, Codex CLI, OpenCode CLI, Pi CLI). Kimi, OpenCode, and Pi are also available as CodingAgent `task` subagent engines.

If you're here for the architecture deep-dive, jump to [What is Lemon?](#what-is-lemon).

## Quickstart (Telegram)

### 1. Prerequisites

- Elixir 1.19+ and Erlang/OTP 27+
- A model provider API key (Anthropic/OpenAI/etc.)
- Optional for web tools: Brave Search API key or Perplexity/OpenRouter API key

Node.js is only required for the TUI/Web clients; the Telegram gateway is Elixir-only.

#### Installing Dependencies (If You Have Never Used Elixir)

**macOS (Homebrew):**

```bash
brew install elixir
elixir -v
```

Optional (only if you want the TUI/Web clients):

```bash
brew install node@20
node -v
```

**Linux:**

<details>
<summary>Show Linux install instructions (Arch, Ubuntu/Debian, Fedora, and asdf)</summary>

#### Option A (Recommended): asdf (consistent versions across distros)

Install `asdf` (see the asdf docs for your distro), then:

```bash
asdf plugin add erlang
asdf plugin add elixir

# Pick any Erlang/OTP 27.x + Elixir 1.19.x combo.
# Example (adjust versions as needed):
asdf install erlang 27.2
asdf install elixir 1.19.0-otp-27

asdf global erlang 27.2
asdf global elixir 1.19.0-otp-27

elixir -v
```

If your distro packages are too old to satisfy OTP 27 / Elixir 1.19, `asdf` is the simplest fix.

Build deps if `asdf install erlang ...` fails:

- Arch Linux:
```bash
sudo pacman -Syu
sudo pacman -S --needed base-devel git ncurses openssl wxwidgets-gtk3
```
- Ubuntu/Debian:
```bash
sudo apt-get update
sudo apt-get install -y build-essential git autoconf m4 libncurses5-dev libssl-dev libwxgtk3.2-dev libgl1-mesa-dev libglu1-mesa-dev libpng-dev libssh-dev unixodbc-dev
```
- Fedora:
```bash
sudo dnf install -y @development-tools git autoconf m4 ncurses-devel openssl-devel wxGTK-devel mesa-libGL-devel mesa-libGLU-devel libpng-devel libssh-devel unixODBC-devel
```

#### Option B: OS packages (fastest, version varies by distro)

- Arch Linux:
```bash
sudo pacman -Syu
sudo pacman -S elixir erlang
elixir -v
```
- Ubuntu/Debian:
```bash
sudo apt-get update
sudo apt-get install -y elixir erlang
elixir -v
```
- Fedora:
```bash
sudo dnf install -y elixir erlang
elixir -v
```

</details>

### 2. Create a Telegram bot token

1. In Telegram, message `@BotFather`
2. Run `/newbot`
3. Copy the bot token it gives you

If you plan to use Lemon in a group chat, also set bot privacy appropriately in BotFather (`/setprivacy`) so the bot receives messages.

### 3. Get your chat ID

Methods to find your chat ID:

**Using the Telegram Bot API (no third-party bots):**

Send any message to your new bot, then fetch updates via the Telegram Bot API:

```bash
export LEMON_TELEGRAM_BOT_TOKEN="123456:token"
curl -s "https://api.telegram.org/bot${LEMON_TELEGRAM_BOT_TOKEN}/getUpdates" | python3 -m json.tool
```

Look for `message.chat.id`. For groups/supergroups this is usually a negative number.

**Using a bot (fastest method):**

1. Search for `@RawDataBot` or `@userinfobot` in Telegram.
2. Start the chat and it will return your numerical ID.
3. For group IDs, add the bot to the group and it will display the chat ID (usually a negative number for groups/supergroups).

### 4. Configure Lemon

Create `~/.lemon/config.toml`:

```toml
# Provider keys (pick one)
[providers.anthropic]
api_key = "sk-ant-..."

# Default model behavior (used by native Lemon engine and as a fallback)
[agent]
default_provider = "anthropic"
default_model = "claude-sonnet-4-20250514"

# Optional web tool config (`websearch` / `webfetch`)
[agent.tools.web.search]
provider = "brave" # "brave" or "perplexity"
# api_key = "..." # Brave key when provider = "brave"

[agent.tools.web.search.perplexity]
# model = "perplexity/sonar-pro"
# api_key = "..." # optional if PERPLEXITY_API_KEY/OPENROUTER_API_KEY is set
# base_url = "https://api.perplexity.ai"

[agent.tools.web.fetch.firecrawl]
# Optional fallback extractor for hard pages
# enabled = true
# api_key = "fc-..."

# Telegram gateway (runs locally, you chat from Telegram)
[gateway]
enable_telegram = true
auto_resume = true
default_engine = "lemon"
# Optional fallback cwd for unbound chats/sessions (defaults to ~/).
default_cwd = "~/"

[gateway.telegram]
bot_token = "123456:token"
allowed_chat_ids = [123456789]
deny_unbound_chats = true
drop_pending_updates = true
allow_queue_override = true

# Assistant profile used for Telegram chats (when no binding overrides it)
[agents.default]
name = "Lemon"
system_prompt = 

... (truncated)