Getting Started

A practical guide to installing, configuring, and using Matrix. The test-driven methodology is built into the system — agents write tests before implementation, run the full suite before completing tasks, and question architecture when tests reveal problems. 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.

Starting an Agent

Matrix uses mxd send to interact with agents:

# Start an agent with a goal (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"

mxd send <message> sends the message to the root agent. Use -p to target a project by name, -t to target a specific task by ID. The agent auto-detects the project from your current directory, sends the prompt, and enters watch mode.

Interacting with a Running Agent

# Watch agent activity in real-time
mxd watch

# Check what's running
mxd agent

# Send a follow-up message
mxd send "Also add pagination to the list endpoint"

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

# Stop the agent
mxd stop

Web UI 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. The CLI also auto-authenticates its own requests using short-lived JWTs.

Web UI

Open http://localhost:7433 in your browser.

The UI has two main areas:

1. Task Tree (left sidebar) — Shows all tasks in a hierarchy. Click a task to view its activity log. Colors indicate status: blue = in progress, green = passed, red = failed, gray = draft.

2. Activity Log (main area) — Shows the selected agent's conversation: text output, tool calls (expandable cards), and messages from other agents. Text streams in real-time via SSE.

Slash Commands

Type these in the message input:

Command	Effect
/compact	Manually trigger context compaction
/stop	Stop the running agent
/clear	Clear session history
/settings	Open the settings panel

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).

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. passed — Agent completed successfully.
5. failed — Agent called done("failed") or was interrupted. Can be retried.
6. closed — Merged and cleaned up. For persistent tasks, closing resets to pending instead.

Persistent Tasks

Some tasks are persistent — they run periodically rather than once. Their definitions are stored in .mxd/tasks/<id>.json (git-tracked), and closing them resets their status to pending rather than closed.

Persistent tasks have two modes:

• reset — Clean start each cycle. Session history (JSONL) is deleted on close.
• continue — Resume with context. Session history is kept on close.

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.
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