Troubleshooting

Installation Is Required

If a command reports that installation is incomplete, run:

mate install

Mate records install state separately for each companion context. A changed companion configuration, changed dependency plan, missing tool, or Mate update can make that state stale. In a non-interactive process, use:

mate install --yes

Inspect The Active Context

mate doctor

Check the reported state, companion path, repository ID, allowed agents, capabilities, and missing commands. The expected launch state is linked-working-repository.

No Companion Is Found

Run the link wizard from the working repository:

cd /path/to/working-repo
mate companion link

The command requires a TTY. If you are inside a subdirectory, Mate searches upward for the nearest .mate/config/registry.yaml.

Multiple Companions Match

The working repository can have more than one valid companion pointer. Run the command in a TTY so Mate can prompt for a choice. For scripts, pin the context:

MATE_ARTIFACT_PATH=/path/to/companion \
MATE_REPO_ID=my-repo \
mate claude

If a pointer refers to a directory that no longer exists, Mate drops that stale pointer from the repo-local registry.

A TTY Is Required

These workflows are interactive:

• mate companion setup selection
• mate companion link
• mate companion tui

Run them from a local terminal. Setup can accept explicit selection flags, but initializing an unrecognized directory may still ask for confirmation.

Agent Launch Fails

Launch only from the linked working repository:

mate claude
mate opencode

If the companion’s allowed agents list disallows the requested agent, re-run setup and allow that provider. If the agent command itself is missing, use mate doctor to find the missing requirement.

Forward agent-specific flags after --:

mate opencode -- --continue

Companion Git Synchronization Fails

When Git auto mode is enabled, Mate fetches the configured upstream and merges it before syncing managed companion files. Resolve unfinished operations or conflicts in the companion repository, then retry the launch. mate companion sync runs the same synchronization without launching an agent.

To bypass synchronization for one launch:

mate claude -- --no-git
mate opencode -- --no-git

The switch must appear after the argument separator. Mate protects managed paths during conflict recovery, but unrelated conflicts still require manual resolution.

A Plain Session Starts Without Companion Guidance

Plain opencode and plain claude in a wrapped repository load Mate through ~/.mate/runtime/. Installing or upgrading the package does not create it; any mate run does. Run mate doctor (or mate opencode / mate claude) once after installing or upgrading. If Mate is uninstalled, run mate unwrap in the repository.

A Capability’s Claude Plugin Does Not Load In Plain claude

Run mate doctor. Its Claude Plugins table has a Plain Sessions column showing how each plugin folder reaches plain sessions:

• A marketplace name means the wrap enables the folder. Check that Claude Code trusts the repository folder, since Claude Code ignores the repository’s marketplaces until it does. A Capability enabled since the last preparation loads from the next session, or right away after mate wrap.
• no and a reason means the folder is not published, so it loads only with mate claude. When the reason is that the name is already in use, your Claude Code configuration declares a marketplace of that name with another source. A common case is context-mode added from GitHub. Remove that marketplace, or keep using mate claude for this plugin.
• A mate-plugin-… marketplace name means Mate publishes the folder through its own marketplace file, which it writes at the next pass. If mate wrap notes that Mate could not write that file, make the folder’s .claude-plugin directory writable and run mate wrap again. Until then the folder loads only with mate claude, and plain sessions report nothing about it.

Warning: Restart With mate opencode Or mate claude

A plain opencode or claude session in a wrapped repository syncs the companion in the background, fast-forward only, and cannot prompt. A diverged history, a local edit the update would overwrite, or an unreachable remote leaves the session on the current companion with this warning. Restart with the managed launch the warning names (mate opencode or mate claude); its attended sync can resolve it.

Artifact Write Blocked By The Guardrail

Agent artifacts (plans, specs, notes, and most Markdown) belong in the companion, not the working repository. The guardrail refuses a write that would create one in the working repository, and the refusal names the target and the companion:

mate guardrail: artifact writes must go to the companion framework path.
 target:    notes/handoff.md
 resolved:  /work/acme/notes/handoff.md
 companion: /home/me/.mate/companions/acme
 suggested: /home/me/.mate/companions/acme/notes/handoff.md
Relative paths resolve against the working repository; a preceding `cd` is not followed.
Rewrite to the suggested absolute path and retry.

The guardrail resolves a relative path against the working repository, even after a cd into the companion in the same shell command. resolved: shows the path it judged, and appears only for a relative target. suggested: is the matching companion path, offered only when the target lies inside the working repository. Write artifacts with absolute companion paths. A path that is gitignored, or a file already tracked, stays writable in the working repository.

Commit Refused For A Co-Authored-By Trailer

An agent commit whose message credits an AI model as co-author is refused before the commit is created:

Mate guardrail: Co-Authored-By trailers that credit an AI model are not allowed in this repository.
No commit was created. Rerun the same commit without the Co-Authored-By trailer; do not amend or rewrite history to remove it.

Nothing needs to be undone. Rerun the commit without the trailer. A human co-author trailer is allowed. See Commit Attribution.

A Launch Waits For Another Sync

Every companion sync holds one lock per companion under ~/.mate/locks/. A launch waits for another running sync; session-start preparation skips instead. A lock left by a process that no longer runs is cleared automatically.

Update Fails

Self-update works only when Mate was installed globally through npm. Check the current version without changing anything:

mate update --check

If self-update reports that the installation is not npm-managed, reinstall the published package:

npm install -g @uniqbit/mate
mate install

Capability Indexing Fails

Run the indexer explicitly to isolate the failing capability:

mate cap index --graphify
mate cap index --tokensave

Then run mate doctor and verify the relevant capability and command are selected and installed. TokenSave uses a repo-local .tokensave store; Graphify and TokenSave cannot be forced together in one command invocation.