Mewla

Every agent you run, in one hand.
A phone app and a small daemon on your own computer. Every coding agent and shell there becomes a Session you can read as chat, drive as a live terminal, or hand to a Brain that splits the work.

Mewla is for one person running many coding agents. A Go daemon runs on your
Linux or macOS machine next to your repositories, tmux and agent CLIs. The
Android and iOS app connects to it. Mewla is in beta; see Status.

Visit the Mewla homepage for an interactive overview.

Sessions

Start Claude, Codex, Cursor, Grok, Pi, OpenCode, DSH or a plain Shell in any
directory on the host. Each one is a tmux session, so it is also there at the
desk. On the phone, open a Session as structured Chat (messages, tool calls,
plans, attachments) or as the live Terminal, rendered natively with
libghostty. Git shows read-only All, Working and Staged diffs for its
repository. Chat works with the six agent clients; any other command gets the
terminal.

Brain

Give Brain a goal once. It records each part as durable Work, picks a Worker
for it, reads the result and decides what happens next. Workers are ordinary
Sessions; open any of them and take over. Only Brain or you can mark Work done.

Brain's routing guide is routing.md, a few lines of Markdown in its
workspace. It reads the guide before each spawn to choose the executor, model
and reasoning level, and rewrites a line when you state a preference.
mewla brain use <executor> moves Brain itself to another client and keeps its
thread.

Details: Architecture, Brain and Work,
Work lifecycle, Worker routing.

Around the agents

Everything reads from the one server the app is connected to.

Model Providers: official login or your own OpenAI, Anthropic, DeepSeek, OpenRouter or custom gateway keys, stored on the daemon.	Skills: the Skills and Agent Plugins your agents load, where each copy came from, and exact-copy removal.
Plugins (preview): Linear, Notion, GitHub, Slack, Google Workspace, custom MCP and OpenAPI. Read by default; changes are a separate switch.	Usage: tokens, sessions and cost per model, with reported, estimated and unknown costs kept apart.
Calendar: events, reminders, deadlines and scheduled actions that run as visible Work and post back to their Brain thread.	Services: ports your Sessions opened, by project, with an optional temporary Cloudflare Quick Tunnel.
Resources: CPU, memory, disk and pressure, with processes attributed to Workers, Brain, Docker or you.	Alerts and Telegram: push only when a Session is blocked, fails or finishes; Telegram as a second channel to the same Brain.

Quick start

Requirements: Linux (amd64/arm64), WSL2 or an Apple Silicon Mac, with
tmux and at least one authenticated agent CLI on PATH.

# 1. Install the daemon (checksum-verified, no sudo, no telemetry)
curl -fsSL https://raw.githubusercontent.com/daoleno/mewla/main/install.sh | sh

# 2. Check the host, then start on a trusted private network.
#    With no device paired yet, mewla prints a pairing QR code and link.
mewla doctor
mewla --lan

1. Install the app: the Android arm64 APK from
   Releases (see Install),
   or build iOS from source (see Install).
2. Scan the QR code (or paste the link in Settings > Pair Server), then open Brain.
3. Later devices: run mewla pair for a fresh code, or open Mewla in a browser on an
   HTTPS address and approve it from a paired device by matching the number it shows.

Away from your LAN, use Tailscale (mewla -addr "$(tailscale ip -4):9876"), or a
Cloudflare Tunnel or reverse proxy with mewla pair https://your-origin. See
Connect and pair.

One owner

Mewla serves one person. The daemon has an Ed25519 identity; a phone enrolls once
with a short-lived pairing code, then signs every request. The app follows
exactly one current server, and switching servers never mixes their data.
Repositories, credentials and agent state stay on your host. Paired phones see
what you open; model providers see what agents send them.
Security and privacy.

Everyday commands

mewla doctor                         # diagnose tmux, state, port and executors
mewla pair [origin]                  # new one-time pairing code
mewla devices list                   # paired phones
mewla devices revoke -id <device-id>
mewla update                         # verify and install the latest release

mewla brain executors --json         # Brain host and available executors
mewla brain use <executor>           # switch the agent that runs Brain
mewla brain work list --json         # open Work (-all, -full, -id for history)
mewla brain work update -id <work> -status done

mewla worker list --json             # visible Workers
mewla worker capture -id <id> --json # transcript
mewla worker receipt -id <id> --work-id <work>  # was an input accepted?
mewla worker send -id <id> --work-id <work> -text "follow-up"
mewla worker close -id <id>

Configure executors

No configuration is required: built-in defaults cover codex, claude,
agent (cursor-agent), grok, pi and opencode. One installed,
authenticated CLI is enough. To customise:

cp executors.example.toml ~/.mewla/executors.toml   # then restart mewla

[!WARNING]
Several defaults bypass approval prompts so agents can work unattended:
cursor-agent --force --sandbox disabled, grok --permission-mode bypassPermissions,
and Brain-delegated Codex adds --dangerously-bypass-approvals-and-sandbox.
On machines with secrets or production access, use the safe profile in
executors.example.toml. See
Executors.

Model endpoints and API keys for Codex and Claude are set in the app under
Settings > Agents > Model Providers. They are stored on the daemon, never
shown back, and are separate from the Brain executor choice.

Status

Known release issues: docs/release-blockers.md.

Development

bun install                              # workspace deps (Bun 1.3)

# Daemon
bun run daemon:build                     # builds bin/mewla
cd daemon && go test ./...
cd daemon && go run ./cmd/mewla-dev        # hot-reloading dev daemon

# App
bun run app:start                        # Expo dev server
bun run app:android                      # needs Java 17
bun run app:ios
cd app && bun test && bunx tsc --noEmit

# Landing page (static, in site/)
bun run site:dev                         # prints the local preview URL

Layout: daemon/ Go daemon (cmd/mewla, server, auth, brain, work,
lifecycle, terminal, watcher); app/ Expo app (routes in app/app/,
components, services, store); docs/ product and operator docs; site/
landing page, whose site/assets/*.svg drawings this README also uses
(regenerate with python3 scripts/site-svg/build.py);
scripts/ build and release tooling.

The native terminal uses libghostty; see Android
and iOS for build contracts.
All documentation starts at docs/README.md.

Contributing

Read CONTRIBUTING.md and AGENTS.md. Keep
changes small, run the relevant checks, and never commit pairing links, ~/.mewla
state, tunnel URLs or .env.local. Report vulnerabilities as described in
SECURITY.md.

License

Apache License 2.0; see LICENSE and NOTICE. The Mewla name
and logos are covered by TRADEMARKS.md.