Installation

Install The CLI

Mate is published to npm and requires Node.js 24.

npm install -g @uniqbit/mate

The published package bootstraps Bun when Bun is not already available. Bun is Mate’s core runtime package manager.

Install Core Requirements

Before linking a companion, run Mate’s installer from the working repository:

cd /path/to/working-repo
mate install

Without a linked companion, mate install verifies the core runtime and saves the core installation state. Use the non-interactive form in CI or another process without a TTY:

mate install --yes

Link A Companion

mate companion link

The link wizard can select a registered companion or clone a Git-backed companion. For GitHub URLs, Mate tries SSH before HTTPS. The working repository gets local metadata at:

.mate/config/framework.yaml
.mate/config/registry.yaml

Mate adds .mate/ to .git/info/exclude, so these machine-local pointers do not need to be committed. The repo-local registry is the source of truth when Mate resolves a working repository.

Linking builds a dependency plan from the selected companion configuration, checks which requirements are already available, installs missing requirements, and saves the companion-specific install state. It does not enable capabilities that were not selected. This makes the default workflow:

mate install
mate companion link
mate opencode

Run installation again after any of these changes:

the Mate package is installed or updated (this also refreshes ~/.mate/runtime/, which repositories wrapped for OpenCode depend on)
companion capabilities or package managers change
the active companion changes
a required command is removed from PATH

Create Or Reconfigure A Companion

mate companion link can clone and initialize a Git-backed companion; see Create A Companion for both ways to start one. Run setup directly only when creating a local companion or changing its policy and capability selections:

cd /path/to/companion-repo
mate companion setup

Setup configures allowed agents, package managers, capabilities, the OpenSpec schema profile, and optional companion Git auto mode. The interactive picker is recommended. Explicit flags are available for repeatable environments:

mate companion setup \
  --allowed-agent claude \
  --allowed-agent opencode \
  --capability openspec \
  --capability react-doctor \
  --package-manager uv \
  --openspec-schema default \
  --git-mode default

Changing setup selections invalidates the companion install state. Run mate install from that companion or a linked working repository afterward.

Verify The Context

mate doctor

Doctor reports the current context, companion path, repository ID, active policy, selected capabilities, and required tool status. It distinguishes:

linked-working-repository
companion-repository
not-linked

Once installation is current, launch from the working repository:

mate opencode
# or
mate claude

Recovery Commands

Mate allows these commands even when normal commands are blocked by stale or missing install state:

mate install
mate doctor
mate companion setup
mate companion link
mate update
mate --help
mate --version

Verify The Package

Every Mate release is published from the repository’s release workflow with an npm provenance attestation that links the package to its source commit and workflow run. npm audit signatures checks the packages of a project, so verify a version from a scratch directory:

mkdir mate-verify && cd mate-verify
npm init -y >/dev/null
npm install @uniqbit/mate@<version>
npm audit signatures

A package without a valid registry signature or attestation is reported as an error.