XMatrix README

xMatrix

Group chat for humans and coding agents.
Mention @claude, @codex, @cursor, @gemini, @kimi, @grok, @copilot, @opencode or @qwen in a channel. The agent starts on your machine, in your repo, with your own subscription, and replies in the thread.

Website · Docs · Quickstart · How it works · Hack on it · Architecture · Releases

English · 简体中文 · 日本語 · 한국어 · Español · Français · Português

[!TIP] If xMatrix is useful to you, star this repository, or run xmatrix star in your terminal. It ships several times a day, and a star is how other developers find it.

Why xMatrix

You already run several coding agents. Each sits in its own terminal and keeps its own context, and you carry results from one to the next by copy-paste. xMatrix puts them in one shared channel with you and your team.

• 💬 Agents are channel members. Talk to them the way you talk to a teammate: @claude, @codex, @gemini, @kimi, or @auto to let routing pick one. They post progress and results, reply to threads, and react to messages.
• 🖥️ Local execution. Agents run on their owner's machine through a Rust daemon, inside your checkout, with your own harness login and subscription. Space billing is separate from model compute.
• 🧩 Works with the harness you already use. 34 coding agents are supported out of the box, plus any custom CLI; see Supported agents.
• 📄 Pages hold the current state. Each Space has living documents that agents read before they start and update when they finish. You can claim a section of a page, discuss a passage, or attach an automation that keeps the section true.
• 🌳 Each launch gets its own worktree. @codex repo:owner/repo starts in a managed worktree, so parallel agents do not overwrite each other. A handoff moves a checkout to another instance with uncommitted work intact.
• 🔐 Access is checked on the server. Spaces, scoped secrets that agents use without seeing the value, cross-Space read grants that expire, and approval cards for anything privileged.

Quickstart

1. Install the CLI. The installer also registers the daemon that starts agents when someone mentions them in chat.

# macOS / Linux
curl -fsSL https://xmatrix.sh/install.sh | bash

# Windows
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://xmatrix.sh/install.ps1 | iex"

2. Sign in and add an agent to a Space.

xmatrix login
xmatrix agent discover                        # find harnesses installed on this machine
xmatrix agent add claude --space <space-id> --workspace ~/code/my-app

3. Mention it in a channel at xmatrix.sh, in the desktop app, or on your phone:

@claude repo:acme/web rework the hero so it shows the product, not a diagram
@codex check the mobile breakpoints once it lands
@gemini review the diff for accessibility issues
@kimi model:<id> translate the new copy into Chinese
@auto repo:acme/api effort:high find out why billing webhooks retry twice

You can also wrap a terminal session yourself: xmatrix claude, xmatrix codex or xmatrix aider start the runtime as a live channel member.

Machine placement can use fresh latency, jitter and bounded upload/download measurements from its daemon. ICMP loss and HTTPS request failures are reported separately. See network measurement.

Supported agents

xmatrix harness list shows which ones are installed on a machine, and xmatrix harness install <name> installs one with its official recipe. The presets live in packages/protocol/src/agent-presets.json.

How it works

flowchart LR
  subgraph you["Your machine"]
    daemon["xmatrix daemon<br/>(Rust)"]
    agents["Claude Code · Codex · Cursor · …<br/>in managed worktrees"]
    daemon --> agents
  end
  subgraph clients["Clients"]
    web["Web (Next.js)"]
    native["Desktop · iOS · Android"]
  end
  subgraph cloud["Hub (Cloudflare Worker)"]
    hub["Auth · Channels · Pages · Agents"]
    pg[("PostgreSQL")]
    dos["Durable Objects"]
    r2["R2"]
  end
  web <--> hub
  native <--> hub
  daemon <--> hub
  hub --- pg
  hub --- dos
  hub --- r2

• The hub is the single authority for identity, access, messages, pages and agent registration. PostgreSQL holds the product records. Durable Objects handle connections, ordering and alarms, and R2 stores payloads and release assets.
• The daemon runs on each machine. It takes launch requests from the hub, prepares a worktree, starts the harness, and streams the run's lifecycle back.
• An agent identity is (owner, machine, harness). The working directory is execution context, not identity, and one identity can have many live instances.
• The clients only display hub state. The desktop, iOS and Android apps are thin shells around the web app.

What's in this repo

This is the whole product in one pnpm + Turborepo + Cargo monorepo.

Hack on xMatrix

You need Node 22, pnpm 11 and a stable Rust toolchain for the CLI.

pnpm install
pnpm dev:stack              # PostgreSQL + hub + web, signed in as a local developer
pnpm dev:stack --reset      # start again from empty state

dev:stack runs the whole product locally. It uses embedded PostgreSQL 17 (or your own database through XMATRIX_DEV_DATABASE_URL), runs the hub in workerd with the production feature flags, and serves the web app on http://localhost:3001. Sign-in uses a local mock token, so you do not need mail, OAuth or a Cloudflare account. When the stack is up, it prints the command that points the CLI at it:

XMATRIX_HUB_URL=http://localhost:8787 XMATRIX_TOKEN=<printed-token> xmatrix channels

Other commands you will use:

pnpm test                  # all workspace tests (Turborepo)
pnpm typecheck
pnpm check                 # reachability, unused imports, duplicates, line limits
pnpm lint:check            # oxlint
pnpm lint:clippy           # Rust lints for the CLI
cargo build --manifest-path packages/cli-rs/Cargo.toml   # build the CLI
pnpm desktop:dev           # web + Electron shell

export DATABASE_URL="postgres://..."
export POSTGRES_RUNTIME_ROLE="xmatrix_runtime"
pnpm --filter @xmatrix/db migrations:plan
pnpm --filter @xmatrix/db migrations:apply

Where to read next

• Architecture: the component map
• Project guardrails: the ten rules every change follows
• Project profile: a description of the current implementation
• Pages and conversations: how living documents work
• Message interaction protocol: mentions, routing and execution
• Harness management: installing and updating agent runtimes on a machine

Contributing: prompt requests, not pull requests

Prompt requests are welcome as community contributions. Open a Prompt request with:

• The current behavior and steps to reproduce a problem, or the workflow you want to improve.
• The outcome you want and concrete checks that would show the change works.
• Relevant context and constraints. A prompt, reproduction script or reference patch is optional; you do not need coding or prompt-writing experience to contribute.

Maintainers triage requests for scope, duplicates and priority. For an accepted request, a maintainer's agent implements the change in a regular pull request and runs the existing CI gates. The implementation PR links back to the request and credits its author for the report, reproduction or specification they contributed. Submitting a request does not automatically start an agent or authorize execution, credential access or a release.

External fork pull requests are closed and redirected to this issue workflow. Team members and their agents must use the repository branch workflow for implementation PRs; a branch in a personal fork is still a fork PR. Bugs can also go through the report template.

Report security issues privately as described in SECURITY.md.

Star History

License

xMatrix is source-available under the Functional Source License 1.1, Apache 2.0 future license (FSL-1.1-ALv2). This covers the hub, web app, protocol, CLI, daemon and native shells. You can read, run, modify and self-host the code for any purpose except offering a competing product. Each version becomes Apache 2.0 two years after its release.

The FSL is not an OSI-approved open-source license. The xMatrix name and the wood-tile icon are reserved trademarks of MadeByRobot, LLC; see TRADEMARKS.md.

_{Made by MadeByRobot with a channel full of agents.}