Quickstart

Mate uses two repositories:

• companion repository: stores Mate configuration, skills, and capability output
• working repository: stores the project code agents should edit

Install the published CLI once:

npm install -g @uniqbit/mate

Then use this default flow in the repository you want an agent to edit:

mate install
mate companion link
mate opencode

1. Install Mate Requirements

Move to the working repository and initialize Mate’s core requirements:

cd /path/to/working-repo
mate install

The first install does not require a companion. It verifies Mate’s core runtime and records the installation state for the current environment.

2. Link A Companion

From the same working repository, run:

mate companion link

Mate opens the TUI flow. Use it to select an existing companion, paste a local companion path, or clone one from Git. A cloned companion is configured when necessary. No companion yet? See Create A Companion.

The link is stored in the working repository’s local .mate registry. Mate also adds that directory to Git’s local exclude file so the link metadata is not committed to the working repository. Linking also verifies and installs the requirements selected by the companion, so no second mate install is needed.

3. Launch OpenCode

Start OpenCode:

mate opencode

If the companion’s allowed agents include Claude, you can launch it instead:

mate claude

Mate resolves the linked project, syncs the companion instructions and capabilities, refreshes enabled indexes, then launches the selected agent in the working repository context.

mate opencode also wraps the working repository for OpenCode: it writes Mate’s regions into .opencode/opencode.json and copies the companion’s .opencode/ files as git-excluded files. After that, plain opencode in the repository loads the companion as well. See Wrapping.

Run mate install again after updating Mate or changing a companion’s selected package managers or capabilities. Any mate run also refreshes ~/.mate/runtime/, which wrapped repositories load Mate through.

See Capabilities for the optional tools Mate can wire into the flow.