⚡🛡️ Mayros

AI agent framework · Coding CLI · Personal assistant
One platform. Your terminal, your channels, your devices.

Product · Download · Docs · Getting Started · Vision · Discord

Mayros is an open-source AI agent framework that runs on your own devices. It ships with an interactive coding CLI (mayros code), connects to 17 messaging channels (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Teams, and more), speaks and listens on macOS/iOS/Android, and has a knowledge graph that remembers everything across sessions. All backed by a local-first Gateway and an 20-layer security architecture.

55 extensions · 11,700+ tests · 29 hooks · MCP server & client · Multi-model · Multi-agent

npm install -g @apilium/mayros@latest
mayros onboard
mayros code   # interactive coding CLI

Why Mayros?

Install

Runtime: Node ≥ 22. Works with npm, pnpm, or bun.

npm install -g @apilium/mayros@latest
# or: pnpm add -g @apilium/mayros@latest

mayros onboard --install-daemon

The wizard sets up the Gateway, workspace, channels, and skills. It installs the Gateway as a background daemon (launchd/systemd) so it stays running.

New install? Start here: Getting Started · Upgrading? Updating guide (and run mayros doctor)

Coding CLI

mayros code is an interactive terminal UI for coding, conversation, and agent-driven workflows.

mayros code                    # interactive TUI session
mayros tui                     # alias
mayros -p "refactor auth flow" # headless mode (non-interactive)

Features:

• 🎨 3 themes (dark, light, high-contrast) — /theme
• 📝 3 output styles (standard, explanatory, learning) — /style
• ⌨️ Vim mode with motions, operators, undo — /vim
• 📋 Ctrl+V image paste from clipboard
• 📊 /diff inline diff viewer · /context token usage chart
• 🗺️ /plan semantic plan mode (Cortex-backed)
• 📎 /copy to clipboard · /export [file] to disk
• 🔀 /model switch models · /think set thinking level · /fast toggle fast mode

Slash commands (30+):

Markdown-driven extensibility:

• Custom agents: ~/.mayros/agents/*.md — define persona, tools, and behavior in markdown
• Custom commands: ~/.mayros/commands/*.md — define slash commands as markdown templates

Quick Start

# 1. Install and onboard
mayros onboard --install-daemon

# 2. Start the Gateway
mayros gateway --port 18789 --verbose

# 3. Code interactively
mayros code

# 4. Or use the agent directly
mayros agent --message "Ship checklist" --thinking high

# 5. Or send a message to any channel
mayros message send --to +1234567890 --message "Hello from Mayros"

Full beginner guide: Getting started

Architecture

  WhatsApp · Telegram · Slack · Discord · Signal · iMessage · Teams · Matrix · WebChat
                                    │
                                    ▼
                    ┌───────────────────────────────┐
                    │          ⚡ Gateway             │
                    │     (local control plane)      │
                    │     ws://127.0.0.1:18789       │
                    └──────────────┬────────────────┘
                                   │
          ┌────────────┬───────────┼───────────┬────────────┐
          │            │           │           │            │
     mayros code   VSCode /   Pi Agent    macOS App    MCP Server
      (TUI)       JetBrains   (RPC)      (menu bar)   :19100
                                                     Claude Desktop
                                                     Claude Code

The Gateway is the single control plane — every client, channel, tool, and event connects through it.

Multi-Channel Inbox

Mayros connects to the channels you already use. One assistant, everywhere.

Security defaults: DM pairing — unknown senders get a pairing code. You approve with mayros pairing approve <channel> <code>. Public DMs require explicit opt-in.

Knowledge Graph (AIngle Cortex)

Mayros remembers. Not just conversation history — semantic knowledge stored as RDF triples in AIngle Cortex.

Three-tier memory:

1. MAYROS.md — flat-file persona and instructions, always loaded into the system prompt
2. AIngle Cortex — RDF triple store (subject → predicate → object) scoped by namespace. Optional: falls back to file-based memory when unavailable
3. Ineru STM/LTM — short-term and long-term memory with temporal recall

Built on top:

• Code indexer — scans your codebase → RDF triples in Cortex (incremental, only re-indexes changed files)
• Project memory — persists conventions, findings, and architecture decisions across sessions
• Smart compaction — extracts key information before context pruning
• Cross-session recall — injects relevant knowledge from previous sessions into new prompts

Design principles: namespace isolation (no cross-namespace reads), graceful degradation (Cortex is a sidecar, not an FFI binding), circuit breaker with exponential backoff.

CLI: mayros kg search|explore|query|stats|triples|namespaces|export|import

MCP Server

Mayros exposes its tools, resources, and prompts via the Model Context Protocol. Any MCP client — Claude Desktop, Claude Code, VSCode, Cursor, JetBrains — can discover and use Mayros capabilities.

Connect with Claude Desktop

# 1. Install Mayros
npm install -g @apilium/mayros@latest

# 2. Register with Claude Desktop (auto-detects paths, writes config)
mayros mcp-setup --desktop

# 3. Restart Claude Desktop — done
#    The tools icon appears in the chat input

Then in Claude Desktop, just talk naturally:

• "Remember that our API uses JWT tokens with 24h expiry" → stores in semantic memory
• "What do you know about our authentication?" → recalls from memory and knowledge graph
• "Store in the graph: project:api depends_on express v5" → creates an RDF triple
• "What's the memory status?" → shows STM/LTM/graph statistics

Connect with Claude Code

# From your terminal (not inside a Claude Code session)
mayros mcp-setup
# or manually:
claude mcp add mayros -- mayros serve --stdio

Connect with other MCP clients

# Start the HTTP server
mayros serve --http
# → MCP endpoint: http://127.0.0.1:19100/mcp
# → Legacy SSE:   http://127.0.0.1:19100/sse
# → Health check: http://127.0.0.1:19100/health

Point any MCP client to http://127.0.0.1:19100/mcp (Streamable HTTP) or http://127.0.0.1:19100/sse (legacy SSE for older clients).

Tools

Intelligent Routing

Adaptive routing that learns and improves over time.

• Eruberu (Q-Learning model routing) — learns optimal provider/model per task type, budget level, and time slot
• Miteru (task-to-agent routing) — learns which agent handles each task type best via EMA scoring
• Hayameru (code transforms) — deterministic WASM transforms that bypass the LLM for simple edits (var→const, remove console, sort imports). 0 tokens, sub-millisecond

CLI: mayros routing status|strategy|reset

Multi-Agent Mesh

Agents that work together. Mayros supports coordinated multi-agent workflows with shared knowledge.

• Team manager — Cortex-backed lifecycle: create, assign roles, merge results, disband
• Workflow orchestrator — built-in workflows (code-review, research, refactor) + custom definitions
• Kimeru consensus — majority vote, weighted (EMA), LLM-arbitrated, Byzantine (PBFT with HMAC), Raft leader election
• Agent mailbox — persistent inter-agent messaging (send/inbox/outbox/archive)
• Background task tracker — long-running tasks with status and cancellation
• Git worktree isolation — each agent works in its own worktree to avoid conflicts
• Session fork/rewind — checkpoint-based exploration with rewind capability
• Kakeru bridge — dual-platform coordination (Claude + Codex CLI) with file lock coordination

CLI: mayros workflow run|list · mayros dashboard team|summary|agent · mayros tasks list|status|cancel|summary · mayros mailbox list|read|send|archive|stats

IDE Plugins

Mayros lives inside your editor, connected via Gateway WebSocket.

VSCode (tools/vscode-extension/):

• Sidebar tree views: sessions, agents, skills
• Webview panels: chat, plan mode, trace viewer, knowledge graph
• Context menu actions and gutter markers

JetBrains (tools/jetbrains-plugin/):

• Unified tabbed panel with the same feature set
• Protocol v3 compatibility

Both connect to ws://127.0.0.1:18789.

Voice & Companion Apps

• Voice Wake + Talk Mode — always-on speech for macOS/iOS/Android with ElevenLabs
• Live Canvas — agent-driven visual workspace with A2UI
• macOS app — menu bar control, Voice Wake, Talk Mode overlay, WebChat, debug tools
• iOS node — Canvas, Voice Wake, Talk Mode, camera, screen recording, Bonjour pairing
• Android node — Canvas, Talk Mode, camera, screen recording, optional SMS

Extensions Ecosystem

55 extensions loaded as plugins at startup:

Hooks System

29 hook types across the assistant lifecycle:

• Lifecycle — before_prompt_build, after_response, before_compaction, agent_end, etc.
• Security — permission_request (modifying: allow/deny/ask), config_change
• Coordination — teammate_idle, task_completed, notification
• HTTP webhooks — POST delivery with HMAC-SHA256 signatures, retry + exponential backoff
• Async queue — background execution with concurrency limits and dead-letter queue
• Markdown hooks — place .md files in ~/.mayros/hooks/ for custom logic

Security (20 layers)

Mayros takes security seriously. 20 layers of defense:

Models

Mayros is multi-model. Bring any provider.

• Models config + CLI: Models
• Auth profile rotation (OAuth vs API keys) + fallbacks: Model failover

Minimal config:

{
  agent: {
    model: "anthropic/claude-opus-4-6",
  },
}

Full reference: Configuration

Plan Mode

Cortex-backed semantic planning for complex multi-step tasks.

• Explore — gather context from the codebase and Cortex graph
• Assert — declare facts and constraints the plan must satisfy
• Approve — review the plan before execution
• Execute — run the approved plan with progress tracking

CLI: mayros plan start|explore|assert|show|approve|execute|done|list|status · TUI: /plan

Remote Gateway

Run the Gateway on a small Linux instance. Clients connect over Tailscale Serve/Funnel or SSH tunnels, and device nodes (macOS/iOS/Android) handle local actions via node.invoke.

Tailscale modes: off (default) · serve (tailnet-only HTTPS) · funnel (public HTTPS, requires password auth).

Details: Remote access · Tailscale guide · Docker

Chat Commands (Channels)

Send these in WhatsApp/Telegram/Slack/Discord/Google Chat/Microsoft Teams/WebChat:

From Source

git clone https://github.com/ApiliumCode/mayros.git
cd mayros

pnpm install
pnpm ui:build   # auto-installs UI deps on first run
pnpm build

pnpm mayros onboard --install-daemon

# Dev loop (auto-reload)
pnpm gateway:watch

pnpm mayros ... runs TypeScript directly (via tsx). pnpm build produces dist/.

Development channels:

• stable — tagged releases, npm dist-tag latest
• beta — prerelease tags, npm dist-tag beta
• dev — moving head of main, npm dist-tag dev

Switch: mayros update --channel stable|beta|dev. Details: Development channels

Skills Hub

Skills Hub is a skill marketplace. With it enabled, the agent can search for skills automatically and pull in new ones.

• Workspace root: ~/.mayros/workspace
• Skills: ~/.mayros/workspace/skills/<skill>/SKILL.md
• Injected prompt files: AGENTS.md, SOUL.md, TOOLS.md

Channel Setup

{ channels: { telegram: { botToken: "123456:ABCDEF" } } }

{ channels: { discord: { token: "1234abcd" } } }

Documentation

Start here:

• Getting started — first-time setup
• Architecture — gateway + protocol model
• Configuration — every key + examples
• Security — security model and guidance

Platform guides:

macOS · iOS · Android · Linux · Windows (WSL2)

Operations:

Gateway runbook · Docker · Health checks · Doctor · Logging · Troubleshooting

Deep dives:

Agent loop · Sessions · Models · Presence · Streaming · Skills · Browser · Canvas · Nodes · Cron · Webhooks · Gmail Pub/Sub

Advanced:

Discovery + transports · Bonjour/mDNS · Gateway pairing · Tailscale · Remote gateway · Control UI · RPC adapters · TypeBox schemas

Templates:

AGENTS · BOOTSTRAP · IDENTITY · TOOLS · USER · Default AGENTS · Skills config

Community

See CONTRIBUTING.md for guidelines, maintainers, and how to submit PRs. AI/vibe-coded PRs welcome! 🤖

Special thanks to Mario Zechner for his support and for pi-mono.