Public Repo Basics

This document covers the conventions every contributor needs to know when working in this repository.

Prerequisites

• Elixir 1.19.5+ and Erlang/OTP 28.5+
• Node.js 24 LTS+ (for clients/lemon-web)
• Bun 1.3.14+ (for clients/tui)
• A configured ~/.lemon/config.toml with at least one provider API key

Development setup

# Install Elixir dependencies
mix deps.get

# Install TUI dependencies
cd clients/tui && bun install

# Install web dependencies
cd clients/lemon-web && npm install

Running locally

# Start the Lemon runtime in dev mode
./bin/lemon daemon

# Start the dev-mode TUI
./bin/lemon-tui

# Start the gateway
./bin/lemon-gateway

Running tests

# All Elixir tests
mix test

# A specific app
mix test apps/lemon_core

# TUI checks and tests
cd clients/tui && bun run check && bun test

Code ownership

See docs/contributor/ownership.md for the directory-to-owner mapping and the CODEOWNERS rules.

Branching and PRs

• Branch off main for all work.
• Branch names: <type>/<short-description>, e.g. feat/session-search.
• PRs require approval from the owners listed in CODEOWNERS.
• Cross-cutting changes (e.g. mix.exs, shared schemas) require @z80 sign-off.

Commit style

This repo uses Conventional Commits:

<type>(<scope>): <short description>

[optional body]

Common types: feat, fix, docs, refactor, test, chore.

Scope should be the app name or domain: lemon_core, lemon_skills, agent_core, config, gateway, etc.

Feature flags

New behaviour that spans multiple milestones must be gated behind a feature flag in [features] (see docs/config.md). Do not introduce ad-hoc System.get_env checks for features — use LemonCore.Config.Features.

File ownership rule

New files inherit the owner of their nearest directory entry in .github/CODEOWNERS. If your new file falls outside any existing glob, add an explicit entry before the PR merges. See docs/contributor/ownership.md for details.