Getting Started

A practical guide to installing, configuring, and using Matrix. Quality practices are built into the system prompt that every agent receives. Agents write tests before implementation, question architecture when tests reveal problems, and preserve decisions in the task tree. You don't need to configure this; it's how Matrix works by default.

Prerequisites

• Bun — JavaScript runtime and package manager. Install:

  curl -fsSL https://bun.sh/install | bash

• Git — Must support worktrees (Git 2.5+; any modern version works).
• An Anthropic API key — Get one at console.anthropic.com. OpenAI-compatible keys also work, but Anthropic (Claude) is the primary provider.
  • Alternatively: a Claude OAuth token (for Claude Pro/Team subscribers).
• macOS — The daemon management (mxd daemon install) currently uses macOS launchctl. Linux/Windows support is not yet implemented.

Installation

Matrix is not yet published to npm. Install from source:

# Clone the repository
git clone https://github.com/AskEntity/Matrix.git
cd Matrix

# Install dependencies
bun install

# Install the CLI globally
bun link

This creates a global symlink so mxd is available anywhere. Bun's default install puts the link at ~/.bun/bin/mxd — make sure ~/.bun/bin is in your PATH (it is by default for Bun installations).

Configuration

Auth Groups

Matrix uses auth groups to manage provider credentials. An auth group defines which LLM provider and API key to use.

# Add an auth group with an Anthropic API key
mxd config auth add default --provider anthropic --key sk-ant-api03-...

# Or with OpenAI
mxd config auth add openai-group --provider openai --key sk-...

# Or with a Claude OAuth token (for Claude Pro/Team subscribers)
mxd config auth add claude --provider anthropic --oauth-token <token>

# List configured auth groups
mxd config auth list

# Remove an auth group
mxd config auth remove <name>

Auth groups are saved to the global config by default. Add --project to save to the project-level config instead.

OpenAI-Compatible Providers

The --base-url flag lets you use any OpenAI-compatible API (e.g., local models via Ollama, Azure OpenAI, etc.):

mxd config auth add local --provider openai --key sk-... --base-url http://localhost:11434/v1

Three-Layer Config

Configuration is resolved in layers (lower layers have higher priority):

1. Global (~/.mxd/config.json) — Applies to all projects.
2. Repo (.mxd/config.json) — Project-specific, committed to git.
3. Local (per-project, managed by the daemon) — Personal overrides, not in git.

# Set the default model for a project (committed to git)
mxd config set model claude-sonnet-4-6 --project

# Set the default auth group globally
mxd config set defaultAuth default --global

# Set a value in local config (default when no --global/--project flag)
mxd config set childModel claude-sonnet-4-6

# View the fully resolved config (includes MCP servers and auth groups)
mxd config

Available config keys: model, childModel, defaultAuth, childAuth, budgetUsd, clarifyTimeoutMs, maxDepth, mcpServers, port, sessionKeep.

MCP Server Configuration

Connect external tools via MCP (Model Context Protocol) servers. Add them to any config layer:

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-server-puppeteer"],
      "env": {}
    },
    "database": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

MCP server config fields:

• command — The executable to run.
• args — Command-line arguments (optional).
• env — Environment variables (optional).

MCP servers merge across config layers: a project-level server with the same name overrides a global one.

Starting the Daemon

Matrix runs as a background daemon — an HTTP server on port 7433.

# Install as a system service (macOS LaunchAgent) and start it
mxd daemon install

# Manual start/stop
mxd daemon start
mxd daemon stop
mxd daemon restart

# Check status
mxd daemon status

# View logs (last 100 lines)
mxd daemon logs
mxd daemon logs -f          # follow (tail -f)
mxd daemon logs --err       # stderr log
mxd daemon logs -f --err    # follow stderr

# Uninstall the service
mxd daemon uninstall

# Or run in foreground for development
bun run dev

The daemon serves:

• A REST API for all operations
• A web UI at http://localhost:7433
• An SSE endpoint for real-time event streaming

Creating a Project

A project in Matrix is a git repository registered with the daemon.

# Register the current directory
mxd init .

# Or specify a path
mxd init /path/to/your/project

# List registered projects
mxd list

The init command:

1. Registers the repository with the daemon.
2. Creates the .mxd/ directory if needed.
3. Creates .mxd/memory.md — the project's persistent memory file.
4. Sets up git hooks for worktree support.

Web UI

The web UI is Matrix's primary interface. Open http://localhost:7433 in your browser.

Authentication

The web UI uses a challenge-response authentication flow based on RSA-OAEP encryption:

1. Open http://localhost:7433 in your browser.
2. The login page generates an RSA keypair and displays a CLI command: mxd auth <public_key>.
3. Copy and run that command in your terminal.
4. The CLI encrypts a session JWT with the public key and prints the ciphertext.
5. Paste the ciphertext back into the web UI.
6. The browser decrypts it with its private key to obtain the session token.

This ensures only someone with CLI access (i.e., access to ~/.mxd/auth.json) can authenticate to the web UI.

Layout

The UI uses a tab-based layout inspired by VSCode:

1. Task Tree (left sidebar) — Collapsible and resizable. Shows all tasks and folders in a hierarchy. Click a task to open a preview tab; double-click to pin it. Colors indicate status: blue = in progress, green = verify, red = failed, gray = draft.

2. Task Tabs (main area) — Each open task gets its own tab. A view mode switcher toggles between:

   • Activity — Live streaming conversation: text output, tool calls (expandable cards), and messages from other agents. Text streams in real-time via SSE.
   • Description — The task's goal, context, and scope.

Interacting with Agents

• Type a message in the input box and press Enter to send.
• The message is delivered to the agent's queue.
• The agent processes it at the next cancellation point (between tool calls).
• Send a message to the root agent to start working on a goal. The orchestrator decomposes work, spawns sub-tasks, and drives to completion.
• Click any task in the tree to open its tab and send messages directly to that agent.

Slash Commands

Type these in the message input:

Command	Effect
/compact	Compact agent context
/stop	Stop the running agent
/clear	Clear all session history
/settings	Open settings panel

CLI

The CLI is an alternative interface for terminal-oriented workflows. Everything the web UI does can also be done from the command line.

Starting and Messaging Agents

# Send a message to the root agent (auto-detects project from current directory)
mxd send "Build a REST API for user management with CRUD endpoints"

# Target a specific project with -p
mxd send -p my-api "Fix the authentication bug"

# Target a specific task with -t
mxd send -t <taskId> "Try using the v2 API instead"

Monitoring

# Watch agent activity in real-time
mxd watch

# Check what's running
mxd agent

# Stop the agent
mxd stop

Task Lifecycle

Tasks flow through these statuses:

1. draft — Idea captured, not ready to execute.
2. pending — Ready to execute, waiting to be started.
3. in_progress — Agent is actively working.
4. verify — Agent called done("passed") — the node status becomes verify (not "passed"). The task above reviews the work, merges the branch, and calls close_task.
5. failed — Agent called done("failed") or was interrupted. Can be retried with send_message (preserves context) or reset_task (fresh start).
6. closed — Merged and cleaned up. Can be reactivated with send_message.

Common Workflows

Simple Single Task

mxd send "Fix the bug in user authentication"
# Agent works autonomously — analyzes code, makes changes, runs tests, commits

Complex Multi-Task

mxd send "Refactor the payment module to use Stripe instead of PayPal"
# The orchestrator will:
# 1. Analyze the codebase
# 2. Create sub-tasks (remove PayPal, add Stripe types, implement API, update tests)
# 3. Spawn worker agents in parallel on separate git worktrees
# 4. Merge results
# 5. Run full test suite

Interactive Collaboration

mxd send "Build the new dashboard page"
# ... agent starts working ...
mxd send "Use the shadcn/ui component library instead of custom components"
# Agent receives the message and adjusts its approach

Continuing a Failed Task

mxd status                      # See the task tree and find the failed task ID
mxd send -t <taskId> "Try using the v2 API instead"

CLI Reference

Messaging
  mxd send <message>               Send message to root agent (auto-detect project)
  mxd send -p <id> <message>       Target a specific project
  mxd send -t <id> <message>       Target a specific task

Project
  mxd init [path]                  Initialize a project
  mxd list (ls)                    List all projects
  mxd relocate <id> <path>         Update project path (after directory move)

Agent
  mxd stop                         Stop running agent
  mxd agent [id]                   Check if an agent is running

Tasks
  mxd status (st) [id]             Show task tree
  mxd tasks [id]                   List tasks with cost details
  mxd delete (del) <taskId>        Delete a task and descendants
  mxd cost [id]                    Show cost breakdown by task

Logs & Sessions
  mxd logs (log) [-n N] [id]       Show event history (last N events)
  mxd watch (w)                    Watch live agent activity
  mxd sessions clear               Clear session history
  mxd sessions prune [--keep N]    Prune old session files (default keep 10)

Config
  mxd config (cfg)                 Show resolved config (global + project + MCP servers)
  mxd config set <key> <value>     Set a config value [--global|--project]
  mxd config unset <key>           Remove a config value [--global|--project]
  mxd config auth add <name>       Add auth group (--provider, --key, --oauth-token, --base-url)
  mxd config auth list             List auth groups
  mxd config auth remove <name>    Remove auth group [--global|--project]

Daemon
  mxd daemon install               Install as macOS LaunchAgent and start
  mxd daemon uninstall             Stop and remove LaunchAgent
  mxd daemon start/stop/restart    Manage daemon
  mxd daemon status                Check daemon status (launchctl + HTTP health)
  mxd daemon logs [-f] [--err]     View daemon logs (-f to follow, --err for stderr)

Auth
  mxd auth <public_key>            Encrypt session token for web UI login

Other
  mxd health                       Check daemon HTTP health
  mxd version (-v, --version)      Show version and git hash

CLI Aliases

Several commands have short aliases shown in parentheses above: ls, st, w, log, cfg, del.

Troubleshooting

Problem	Solution
"Connection refused"	Daemon not running. Run mxd daemon start.
"No auth group configured"	Run mxd config auth add default --provider anthropic --key <your-key>.
Agent seems stuck	Send mxd send "What's your current status?" or type /compact in the web UI to trigger context compaction.
High cost	Run mxd cost to check token usage. Set a cheaper model for sub-tasks: mxd config set childModel <model> --project. Use fork_task_context to transfer a large session's knowledge to new tasks — the forked agents inherit the cache prefix, so three 600K forks cost less than one cold start.
Web UI won't load	Check mxd daemon status. If the daemon is loaded but not responding, check mxd daemon logs --err for errors.

Security Notice

Security Warning

Matrix agents have full access to your system. They can read and write any file your user account can access, execute any command, and access the network.

There is no sandboxing or permission system yet. Only use Matrix:

• On development machines, not production servers
• With projects you trust
• While monitoring agent activity