Your First Agent Session

Install Mate, link a companion, and launch Claude Code or OpenCode with your project context.

Audience

Developers who want to try Mate on one of their repositories and already use Claude Code or OpenCode.

Goal

Start an agent in your working repository with the companion’s instructions, skills, and capabilities already in place.

Steps

Install the CLI

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

npm install -g @uniqbit/mate

Install core requirements

Run the installer from the repository you want the agent to edit:

cd /path/to/working-repo
mate install

No companion is needed yet. This verifies Mate’s core runtime.

Link a companion

mate companion link

The link wizard runs in your terminal. Select a registered companion, paste a local companion path, or clone one from Git. Mate writes the link to a local, git-excluded .mate/ directory and installs the requirements the companion selects.

Check the context

mate doctor

The reported state should be linked-working-repository, with the companion path and selected capabilities listed.

Launch an agent

mate claude
# or
mate opencode

The companion’s allowed agents list must include the agent you launch.

Diagram

Install
npm install -g @uniqbit/matemate install
Once per machine, then in the working repository.

Link
mate companion link
Pick or clone a companion and install what it selects.

Launch
mate claudemate opencode
Start an agent with the companion context wired in.

Every launch runs

1Resolve
Find the companion linked to this working repository.

2Sync
Copy companion instructions, skills, and capabilities into place.

3Index
Refresh enabled code indexes such as TokenSave and Graphify.

4Launch
Start Claude Code or OpenCode in the working repository.

Install once, link a companion, then launch from the working repository

Outcome

The agent runs in your working repository with the companion’s guidance, skills, and capabilities loaded. The link stays on your machine and is never committed to the working repository. From now on, mate claude or mate opencode is the only command you need. Each launch syncs the companion again, so its updates reach your next session.

Next, see how the repositories fit together or what the capabilities do.

Your First Agent Session

On this page