matrixclaw GitHub

Open source · MIT · Linux & macOS

Start in the terminal. Approve from your phone.

MatrixClaw is an always-on, local-first AI agent. A small Go daemon owns your sessions — context, tools, approvals, todo lists and memory — so the terminal and Telegram are two windows into the same work. Close one, pick it up in the other, nothing is lost.

curl -fsSL https://raw.githubusercontent.com/Suren878/matrixclaw/main/scripts/install.sh | bash
Read the docs Star on GitHub
  • Claude Code & Codex as subagents
  • 20 provider presets + any OpenAI-compatible API
  • MCP client and server

01 Daemon-first

One daemon owns the work.
Every client is a window.

matrixclawd keeps context, files, tool history, approvals, provider choice, todo lists, memory, usage and schedules in local SQLite. Clients only render that state and send commands.

  • Terminal TUImatrixclaw tui
  • Telegram botruns inside the daemon
  • HTTP APIiOS Swift package
  • Telephony gatewayAsterisk / SIP
  • MCP hostsmatrixclaw mcp serve
matrixclawd local daemon · loopback HTTP API
  • Sessions & runs
  • Approvals
  • Tasks & subagents
  • Todo · memory · usage
  • Reminders & schedules
SQLite · ~/.local/state/matrixclaw
  • LLM providerschosen per session
  • Toolsfiles · shell · web
  • MCP serversstdio or HTTP
  • Codex · Claude Codeexternal agents

Clients render. The daemon owns.

Exiting the TUI closes only the terminal client. Runs, approvals and context live in matrixclawd, so another client picks up exactly where you left off.

Runs survive restarts.

All real work is a persisted run and approvals are durable. After a crash, a call that changes things never reruns without a fresh approval.

One command set everywhere.

/sessions, /provider, /permissions, /context, /continue, /todo — the TUI and Telegram share them, so a change made in one shows up in the other.

02 Long runs

Built for work that takes hours, not one reply.

The native engine keeps going until the job is done — within a budget of steps, active time and tokens. It runs independent calls in parallel, keeps long commands in the background, summarises its own context and ends with a summary instead of a crash.

run · fix-checkout budget 300 steps · 4 h

00 A run starts…

  • 300 · 4 h Default budget for a user run: steps and active time. Subagents get 100 · 1 h. Change it with /budget.
  • 8 Tool calls from one reply run in parallel. Calls on the same directory or MCP server take turns.
  • 80% Of any limit, the model is told to wrap up. At the limit, a final turn without tools reports what is left.
  • 3 → 5 Loop guard: the same call with the same result 3 times in the last 20 gets a warning, 5 stops the run.
  • 120 s A bash command still running after 120 s moves to the background. await waits for it.
  • /continue Resumes a run that stopped on its budget or a loop, with a fresh budget.

03 Approvals

Stay in control without babysitting.

Risky calls pause and show you the diff or the command. Allow once, allow a pattern for good, or say no and tell the model why — the run keeps going either way.

  • default Reads run freely, except where keys and tokens live. Anything that changes files, runs commands or calls a write-capable MCP tool asks first.
  • accept_edits Also allows write and edit inside the working directory.
  • full_auto Allows every call that no rule denies or asks for.

Rules are allow, ask or deny, per session or global, for bash commands, paths, domains and MCP tools. Deny wins over ask, ask over allow — the same check covers runs, the tools API, voice and the MCP server.

Approval required ~/shop
bash go test ./checkout/...
Always: bash: go test:*

✓ Approved · runs once

bash go test ./checkout/... ok 4.2s

the next bash call asks again

04 Subagents

Fan out the work — even to Claude Code and Codex.

One agent tool hands bounded tasks to child runs. MatrixClaw keeps the session, memory, approvals and Telegram; the children do the digging, in parallel.

blocking or background
Wait for the result, or keep working and get it as a message. Up to 4 background subagents per session by default.
isolation: worktree
Each writing child gets its own git worktree, so several run at once. Read-only children always run in parallel.
runtime
matrixclaw, codex or claude — Codex and Claude Code run as children, or back a whole session.
own budget
Children start from the prompt alone, get 100 steps and 1 h, and return only their result. Their approvals show up in your session and chat.

05 Models

Bring any model. Switch per session.

Twenty built-in providers — OpenAI, Anthropic, Gemini, Qwen, DeepSeek, OpenRouter and more — your ChatGPT subscription through Codex, or any OpenAI-compatible URL. The choice belongs to the session, not the install.

  • OpenAI
  • Codex subscription
  • Anthropic
  • Google Gemini
  • Qwen / DashScope
  • DeepSeek
  • OpenRouter
  • Vercel AI Gateway
  • NVIDIA NIM
  • Hugging Face
  • NovitaAI
  • GMI Cloud
  • StepFun
  • Ollama Cloud
  • Kilo Code
  • xAI / Grok
  • Z.AI / GLM
  • MiniMax
  • Kimi
  • AiHubMix
  • + custom endpoints

Your ChatGPT subscription

Pick OpenAI Codex Subscription in setup and sign in — no API key needed.

matrixclaw providers login openai-codex

Any OpenAI-compatible endpoint

Point a custom provider at a gateway or a model you host yourself. Model pickers load live catalogs where a provider has one.

matrixclaw providers verify --catalogs

Per session, from any client

/provider switches the provider and model of the current session — in the TUI or from Telegram.

/provider

Cache-aware, and measured

Prompt caching on Anthropic and on Claude through OpenRouter, cache keys for OpenAI and Codex. /usage shows prompt, cache, output and reasoning tokens.

/usage

06 Modules

More than a coding agent. Your assistant, wired in.

Web, browser, MCP, voice, images, phone calls and schedules are modules of the same daemon. Turn them on from /modules in the terminal or Telegram — changes apply without a restart.

MCP, both ways

Connect stdio or HTTP MCP servers and their tools become MatrixClaw tools, approval-gated unless marked read-only. Or serve MatrixClaw's own tools to another MCP host.

Web search & fetch

web_search through DuckDuckGo with no key, or Tavily, Serper, SearXNG. web_fetch returns a page's main content as markdown and refuses private addresses.

Local voice

Piper and Supertonic 3 speak, Whisper.cpp listens — on your machine. Telegram voice messages are transcribed into the session. Engines start per task, so idle memory stays near zero.

Realtime voice & calls

Speech-to-speech with Gemini Live, Grok Voice or OpenAI Realtime. The optional SIP gateway bridges Asterisk calls into it; telephony_call always asks first.

Browser

With a browser MCP server such as Playwright, the assistant opens pages, clicks, types, waits and takes screenshots.

Reminders & scheduled tasks

One-time reminders and scheduled AI tasks — once or on a cron schedule — run in your session and report to your clients, Telegram included.

Memory, todo & search

memory keeps durable notes you approve. todo_write tracks multi-step work in a TUI panel and the Telegram status. session_search finds past conversations.

Images

generate_image draws through any provider with an OpenAI-compatible images API — OpenAI, xAI, Gemini or your own server — and edits a photo you send, even when the chat model cannot see images. Telegram gets the result as a photo.

07 Local-first

Your machine. Your data.

Everything MatrixClaw knows lives in SQLite and files under your home directory. What leaves the machine follows from what you configure and the tools the assistant uses.

  • The daemon API binds to loopback and needs a bearer token; a public bind is refused unless you opt in.
  • Tools that change things ask by default, and a call that may have started before a crash never reruns without a fresh approval.
  • read and grep refuse credential files: setup.json, daemon.env, the ChatGPT login, Codex and Claude Code credentials.
  • web_fetch reaches public addresses only, re-checked on every redirect and when dialing.
  • The Telegram bot answers one numeric user id; inline and guest requests get a restricted role.
your machine ~/.local/state/matrixclaw
  • sessions
  • messages
  • runs
  • approvals
  • files
  • memory
  • todo lists
  • usage
  • setup
SQLite · stays here

what leaves, and where to

  • Your LLM provider prompts, context, tool results
  • Telegram chat messages, if the bot is on
  • Remote MCP servers the tool arguments sent to them
  • Codex · Claude Code prompts for those runtimes
  • Realtime voice · SIP audio during voice sessions and calls
  • The web searches, fetched pages, commands you approve

08 Where it fits

A persistent runtime, not another chat window.

Looking for an OpenClaw, Claude Code, Codex or OpenCode alternative? MatrixClaw sits between them: an always-on daemon that can also drive the coding agents you already use.

Tool Focus With MatrixClaw
OpenClaw A self-hosted personal assistant across chat apps. Shares the always-on idea and centres it on a terminal coding-agent runtime: approvals, long runs, subagents.
Claude Code · Codex Coding agents in the terminal. MatrixClaw runs them as subagents or whole sessions, and keeps the session, memory, approvals, Telegram and schedules around them.
OpenCode Terminal AI coding. Overlaps there; MatrixClaw leans into always-on personal automation, Telegram access, durable sessions and subagent orchestration.

MatrixClaw is

  • Always-on local daemon
  • Terminal TUI + Telegram on one session
  • Durable runs and approvals
  • Claude Code and Codex as subagents
  • MIT, self-hosted, single owner

It is not

  • A hosted multi-tenant service
  • A browser IDE
  • A distributed worker platform

Early, self-hosted, built for one owner on a developer machine or a small server.

09 Install

Running in one command.

Linux and macOS, amd64 and arm64. Release archives come with checksums.txt.

  1. 1

    Install

    Downloads the release for your OS and CPU, puts matrixclaw, matrixclawd and the telephony gateway in ~/.local/bin, and starts setup.

    curl -fsSL https://raw.githubusercontent.com/Suren878/matrixclaw/main/scripts/install.sh | bash
  2. 2

    Pick a model

    Setup asks for a provider and its key — or a ChatGPT sign-in — and optionally your Telegram bot token.

    matrixclaw setup
  3. 3

    Start working

    Opens the terminal chat for the current directory and starts the daemon when needed. Later, continue from Telegram with /sessions.

    matrixclaw

Installer options bash -s -- …

--voice-runtime
also install Piper, Supertonic, Whisper.cpp and ffmpeg
--version TAG
a specific release instead of the latest
--from-source
build from a checkout (Go 1.26+)
--no-setup
skip the setup wizard

Update & manage

The TUI checks for a newer release on start and asks before updating.

matrixclaw update install
matrixclaw service restart
matrixclaw doctor

Releases Uninstall & more

10 FAQ

Questions, answered.

Anything else is in the docs, which are built from the repository itself.

Is MatrixClaw an OpenClaw alternative?

Yes: an open-source, local-first assistant that stays running and is reachable from the terminal and Telegram, with local state, approvals, MCP tools, memory, scheduled tasks and subagents.

Is it a Claude Code or Codex alternative?

Partly. Those are terminal coding agents. MatrixClaw is a persistent runtime that can use Claude Code or Codex as subagents or session runtimes while it keeps the session, memory, approvals, Telegram access and automation in one daemon.

Is it an OpenCode alternative?

It overlaps for terminal AI work, but focuses on always-on personal automation, Telegram access, durable sessions and subagent orchestration.

What leaves my machine?

Only what you configure: prompts, context and tool results sent to your LLM provider; prompts sent to Codex or Claude Code; audio sent to a realtime voice provider; tool arguments sent to remote MCP servers; Telegram messages when the bot is enabled; and network traffic from tools you approve. Sessions, messages, approvals, files, memory and setup stay in local SQLite and files.

Can I use my ChatGPT subscription?

Yes. Pick "OpenAI Codex Subscription" in setup and sign in with matrixclaw providers login openai-codex. You can also use API keys for OpenAI, Anthropic, Gemini and other presets, or any OpenAI-compatible endpoint.

What does it run on?

Linux and macOS on amd64 and arm64. The installer puts three Go binaries in ~/.local/bin: matrixclaw (CLI and terminal UI), matrixclawd (the daemon) and matrixclaw-telephony-gateway (optional SIP bridge).

Is it ready for teams?

No. MatrixClaw is early and built for one owner on a developer machine or a small server. It is not a hosted multi-tenant service, a browser IDE or a distributed worker platform.

Wake up

The code is real.
Put it to work.

curl -fsSL https://raw.githubusercontent.com/Suren878/matrixclaw/main/scripts/install.sh | bash
Read the docs GitHub