localmelo

A personal agent that runs on your own computer. It works with tools, remembers across chats and talks to your own model server or a cloud API.

Status: pre-alpha; commands and APIs may change before v0.1.0 (due 2026-12-20).

What you can do

• Talk to one main chat in the terminal (melo), the web console (melo serve) or the Mac app: it answers and does short work itself, long work and tasks you ask for run beside it by priority, and a card says what happened.
• Let melo remember across chats: the newer fact wins, and the Memory tab lets you read, edit or forget each note.
• Say a chore once, like every weekday at 8:30, brief me on my calendar: it runs on time, and a check-in tells you what finished.
• Ask for a reminder, like remind me to send the report on Friday at 9: melo shows the date it understood, then tells you at that time.
• Approve what matters: melo asks before commands and file writes, and shows the change.
• Choose Auto for a chat and melo works on its own: routine steps run, a step you did not ask for asks you on a card (Allow once, Allow for this chat for a site, or Deny), and the riskiest are blocked with the reason.
• When a task runs out of steps it reads Stopped, and Continue picks it up where it left off.
• Use the console and the app in English or 简体中文.
• Use oMLX, Ollama, vLLM, SGLang, melo_serve or MLC LLM on your computer, or a cloud API; run one task from a script and get one JSON line.

Install

git clone https://github.com/localmelo/localmelo.git
cd localmelo
uv sync --extra gateway
source .venv/bin/activate

Without uv, see Install with pip.

On a Mac: the app

On a Mac with Apple silicon, one command, run in the clone, builds the app and installs it in ~/Applications without admin rights:

uv run python scripts/build_macos_app.py --install

• Open localmelo from Spotlight: a native window around the web console.
• The menu bar shows how many chats and tasks run, and when one waits for you; with the window put away, a small pill says what Melo is doing.
• It is a development build, signed ad hoc; it needs a Swift compiler (macOS app guide).

Quick start

On a Mac with Apple silicon (macOS 15 or later), oMLX is the recommended model server. Put each model in its own folder of ~/models (how), then serve the folder:

brew tap jundot/omlx https://github.com/jundot/omlx
brew install jundot/omlx/omlx
omlx serve --model-dir ~/models --port 8000

In a second terminal, run a task:

melo --url http://127.0.0.1:8000/v1 --model Qwen3-8B-4bit "What is 6*7?"

With Ollama, pull a model with ollama pull qwen3:8b and run:

melo --url http://127.0.0.1:11434/v1 --model qwen3:8b "What is 6*7?"

• Run melo alone to chat; the first run finds a running server and saves a configuration. With none found, a Mac with Apple silicon shows one list of what it would install (melo_serve, oMLX, a model) and sets it up after one OK; you can skip any item, use a server you already run, or a hosted service instead.
• melo serve starts the gateway and opens the web console in your browser.
• -u and -m are short for --url and --model; old spellings still work.
• melo-task creates and controls the gateway's background tasks.

Learn more

Page	What it has
Website	What localmelo does, the roadmap and what's new
Quickstart	Install, a first task, a saved configuration and the gateway
Architecture	How the parts fit together, and the memory design
Developer guide	Setup, tests, checks and how to send a change
Reference documentation	Every guide and reference page

Security

Warning

Tools run with your account's permissions, and there is no sandbox.

• The model can run shell commands and Python, and read or write any file you can.
• On macOS, a worker run (melo worker) and a saved task can write only in their workspace.
• In Auto mode on macOS, a step also runs in a write sandbox: its files stay in the folder and away from melo's own sign-in.
• The gateway requires authentication and refuses non-loopback binds.
• Its token does not protect against malicious processes under your own OS user.
• Read SECURITY.md and what the checks do.

Contributing

Bug reports, documentation fixes and small pull requests are welcome; the developer guide has the setup, the tests and the checks to run.

License

MIT © The localmelo Authors. See LICENSE.