MEWS

MEWS is an agent construction system.

Create an agent once, run it in any directory, and keep its Sessions after restarts. Connect more computers when you need access to other files, tools, or processing power. You always choose where the work runs.

MEWS is under active development. Breaking changes can require a clean local state.

How it works

MEWS has four main concepts:

• Hub stores the source of truth for the installation.
• Host is a computer that provides files, tools, and agent runtimes.
• Agent defines identity, behavior, tools, and runtime settings.
• Session connects one Agent to one Host and one working directory.

The computer that runs the Hub is also a Host. You can add more Hosts and move the Hub later.

A Session never moves by itself. If an Agent starts in a project on your laptop, its tools continue to run in that project on that laptop. You can resume the Session from another computer, but MEWS does not copy the project or silently move the work.

Quick start

MEWS requires macOS or Linux and Rust 1.88 or newer.

cargo install --path crates/mews
mews setup
mews providers login
mews providers models
mews agents new coder

Start the Agent in a project:

cd /path/to/project
mews agents coder

Or send one prompt:

mews agents coder -p "Summarize this project"

Each Agent invocation creates a new Session. List and resume Sessions explicitly:

mews sessions list
mews sessions <session-id>

While a native Turn runs, steer it at the next safe boundary or queue a new Turn:

mews sessions <session-id> steer "Use the other approach"
mews sessions <session-id> queue "Run the tests after this"
mews sessions <session-id> queued
mews turns <turn-id>

Agents

An Agent has portable identity, configuration, Skills, and extension declarations:

$MEWS_HOME/agents/coder/
├── SOUL.md
├── agent.toml
├── extensions.toml
└── skills/

SOUL.md describes who the Agent is and how it should behave. agent.toml selects its Harness, options, and explicit tool names. An empty tool list means no tools. Wildcard and prefix selectors do not exist.

Complete Skill directory trees and extension requirements are part of the canonical Agent revision at the Hub. Each Host resolves an extension requirement by name to a Host-local implementation. Only declared extensions can publish tools or run hooks. Executable paths and secrets do not become portable Agent content.

The built-in mews Harness runs a small model and tool loop. It includes these tools:

• read
• write
• edit
• bash

MEWS also supports Agent Skills, executable extensions, lifecycle hooks, and external Harnesses through ACP. The native Mews Harness and ACP Harnesses run on the Session Host. Native model calls return to the Hub Router, so provider credentials do not go to Hosts.

Tools run with the Host user's operating-system authority. MEWS is YOLO by default. It has no built-in approval system and is not a sandbox. Extensions can add policy when you want it.

Models and Harnesses

The built-in Harness supports OpenAI, OpenAI Codex, Anthropic, and Google models. Configure credentials and select defaults with:

mews providers login [provider] [account]
mews providers set-key [provider] [account]
mews providers status
mews providers logout <provider> <account>
mews providers models
mews providers reasoning

Each provider can have multiple named accounts. The native Harness assigns each Session to an account with stable routing. If that account returns an authentication or rate-limit error, the router puts it on cooldown and tries the next account that supports the model.

A Harness controls how an Agent talks to models and uses tools. MEWS includes its native Harness and can run supported ACP Harnesses such as Codex and Claude.

mews harnesses list
mews harnesses setup

Harness availability is Host-specific. An Agent keeps only the portable Harness name and options.

Telegram

MEWS can receive private Telegram messages while its Hub daemon runs. Create a bot with BotFather. MEWS uses Telegram long polling, so it does not need a public URL or an open inbound port.

mews channels telegram add cope --allow-user 123456789

The command reads the bot token from TELEGRAM_BOT_TOKEN or asks for it without showing the input. Add or remove authorized Telegram user IDs locally:

mews channels telegram allow <user-id>
mews channels telegram deny <user-id>
mews channels telegram users
mews channels telegram status

Only private text messages from an allowed message.from.id reach the Agent. Each Telegram chat has a separate durable Session for each Agent. Changing the Agent starts a separate Session; selecting a previous Agent resumes its Session. A new Channel Session starts on the Hub Host in the Hub user's home directory. The Telegram configuration does not bind a Host or working directory.

Configuration commands restart the installed MEWS user service. The selected --root must match that service's root. Long replies are split into Telegram messages; retries resume after the last recorded successful send.

Add another computer

Create a short-lived invitation on the Hub machine:

mews hosts invite

Use the printed invitation on the new computer:

mews setup --join '<invitation>'

MEWS uses an encrypted connection between the Hub and Hosts. Its relay only forwards encrypted messages. It is not a VPN and does not provide general remote shell access.

Useful Host commands:

mews hosts list
mews hosts remove <host>
mews hub move <host>

Windows through WSL

MEWS works in WSL2 as a Linux Host. Enable systemd and keep MEWS_HOME on the Linux filesystem, such as /home/user/.mews. Do not keep it under /mnt/c, because MEWS requires Linux file permissions for keys and credentials.

WSL does not stay active only because a systemd service is running. A MEWS Host inside WSL stops when its WSL instance stops. Use Windows-side startup control if the Host must stay available after login or restart.

WSL2 uses a separate network by default. An outbound connection to an external relay works without extra setup. Hosting the relay for other computers can require mirrored networking, a Windows port rule, or a separate relay server. Set an explicit relay URL instead of relying on the default .local name.

WSL1 is not supported by the normal setup flow because it does not support systemd.

What MEWS does not do

MEWS does not:

• synchronize project files between computers
• move a Session when its Host is unavailable
• add hidden memory between separate Sessions
• sandbox Agent tools
• require a cloud account or hosted control plane
• provide a general mesh VPN

It provides small building blocks for durable Agents, explicit execution, replaceable models and Harnesses, and secure access across your own machines.

Development

Mise keeps development state in this repository:

mise run mews -- setup
mise run mews -- status

Reset development state after a breaking schema change:

mise run mews:reset

Run the checks:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace