OpenCode + OpenPets

What this integration does

The OpenCode integration connects OpenCode activity to your OpenPets desktop companion. It has two pieces: an OpenCode plugin for automatic reactions, and an MCP server for intentional OpenPets tool calls.

Part	What it does	Why it matters
OpenCode plugin	Listens to OpenCode activity and maps useful events to pet reactions.	The pet can think, edit, test, wait, succeed, or show errors automatically.
MCP server	Registers OpenPets MCP tools with OpenCode.	OpenCode can intentionally call `openpets_status`, `openpets_react`, and `openpets_say`.
Managed instructions	Adds short safety guidance for OpenPets usage.	OpenCode knows to keep visible pet messages brief and non-sensitive.

Runtime control is local. OpenCode loads the OpenPets plugin or MCP command, those packages use @open-pets/client, and the OpenPets desktop app updates the pet window over local IPC.

Quick install

In the OpenPets desktop app, open Integrations and use the OpenCode card. The card is the simple setup path for one machine: click Install to write global OpenCode setup, or click Configure to inspect the details first.

OpenPets Integrations window showing the OpenCode card ready to install. — The integrations grid. OpenCode is active and ready; Install starts global setup, while Configure opens the detailed setup panel.

Install writes global OpenCode config for the plugin, MCP server, and OpenPets instructions.
Configure opens the detailed global setup page with pet routing, command detection, install/remove, refresh, and config preview.
Restart OpenCode after setup changes so plugin and MCP config are loaded.

Desktop setup is global. It can affect every OpenCode project on that machine. For repository-specific setup, use the project-local CLI command instead.

Global desktop setup

The OpenCode detail panel manages global setup only. It detects OpenCode, shows whether OpenPets global config is installed, lets you choose a pet, and previews the JSON before writing anything.

OpenCode setup detail page showing global setup status, pet routing, advanced detection, install and remove buttons, and config preview. — The global setup panel. Use it to inspect the target config file, selected pet, command path, and JSON preview before installing.

Panel area	Purpose	What it changes
Global connection	Shows whether OpenCode is detected and whether global OpenPets setup is installed, ready, custom, conflicted, or errored.	Reads OpenCode command status and global OpenCode config files.
Pet routing	Chooses which installed pet OpenCode should target.	Adds the pet ID to plugin options and the MCP command.
Advanced detection	Lets you save a full OpenCode command path if `opencode` is not on PATH.	Used for detection and setup checks.
Preview	Shows config file, instruction file, cleanup paths, and JSON preview.	Lets you audit the planned global config before installation.

OpenCode may need npm or network access to load the published @open-pets/opencode plugin unless it is already cached or installed locally.

Customization ideas

Use global setup when you want OpenPets available in every OpenCode project.
Select a pet before installing if you want all global OpenCode activity to target one companion.
Use the config preview to confirm exactly which file will be written.
Use the command path field if your OpenCode binary is installed outside normal PATH locations.

Project-local setup

Project-local setup is better when a repository should own its OpenPets configuration. It keeps plugin config and instructions in the project, so different repos can target different pets or policies.

Project setupbash

npx -y @open-pets/cli@latest configure --agent opencode --pet <pet-id> --cwd .

Setup style	Best for	Files
Global desktop setup	Personal machine-wide OpenCode setup.	OpenCode config directory, such as `~/.config/opencode/`.
Project-local CLI setup	Repos that should explicitly carry OpenPets setup.	`.opencode/opencode.jsonc` and `.opencode/openpets.md`.

If both global and project setup exist, prefer the project-local config for repository-specific behavior and use global setup only as a default.

Managed config and instructions

OpenPets writes plugin, MCP, and instruction entries with managed markers or predictable config shapes. It uses JSONC-aware edits where possible so existing comments and trailing commas can be preserved.

OpenCode config

A project-local config loads the OpenPets plugin and starts the OpenPets MCP server through the OpenPets CLI. Published setup pins the OpenPets package versions it writes.

.opencode/opencode.jsoncjson

{
  "plugin": [["@open-pets/opencode@<version>", { "pet": "<pet-id>" }]],
  "mcp": {
    "openpets": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@open-pets/cli@<version>",
        "mcp",
        "--pet",
        "<pet-id>"
      ],
      "enabled": true
    }
  }
}

The npm plugin package is @open-pets/opencode. The runtime plugin ID exported by that package is open-pets-opencode.

OpenPets instructions

OpenPets writes a small instruction file so OpenCode uses visible pet messages safely and sparingly. Keep your own notes outside the managed block.

.opencode/openpets.mdmd

<!-- OPENPETS:START -->
## OpenPets
OpenPets MCP tools may be available.
Use OpenPets as a short visible status channel for meaningful coding progress:
- Use openpets_say only for brief, user-facing, non-sensitive status updates.
- Do not include code, logs, secrets, URLs, file paths, prompts, or private data.
- Use openpets_react for small visual progress changes.
- Use openpets_status only when checking availability or the targeted pet.
- Do not spam every internal step.
<!-- OPENPETS:END -->

Customization ideas

Add project-specific OpenCode rules outside the OpenPets managed block.
Pin a pet per repository by rerunning setup with a different --pet.
Use --force only when you intentionally want to refresh managed OpenPets entries.

Plugin event reactions

The plugin listens to OpenCode events and turns useful moments into pet reactions. It ignores OpenPets MCP tools so the pet does not react to its own status updates.

OpenCode event	Condition	Reaction	Speech
`chat.message`	Any chat message.	`thinking`	None
`tool.execute.before`	Tool name contains edit, write, patch, or apply_patch.	`editing`	None
`tool.execute.before`	Shell-like tool with test-like args.	`testing`	None
`permission.asked`	Permission request for a non-OpenPets tool.	`waiting`	`Approval needed`
`session.error`	OpenCode session error.	`error`	Short error-pool message
`session.status`	Status becomes `idle`.	`success`	None

Shell/test detection is intentionally coarse. Tool arguments are used only to classify the reaction; they are not copied into speech bubbles.

MCP tools

The MCP server gives OpenCode a deliberate way to talk to OpenPets. Use MCP when OpenCode should intentionally show status, not just react to lifecycle events.

Tool	Purpose	Use it for
`openpets_status`	Checks desktop reachability and target pet.	Setup checks and debugging.
`openpets_react`	Changes reaction without speech.	Quiet progress states.
`openpets_say`	Shows one short safe message.	Meaningful progress, blockers, completion, or review handoff.

Keep speech brief and non-sensitive. Do not put code, logs, file paths, command output, prompts, URLs, tokens, or private data in pet bubbles.

Pet routing

If no pet is configured, OpenCode events target the desktop default pet. If a pet ID is configured, the plugin and MCP command target that pet.

Runtime pathtext

OpenCode
  -> OpenPets plugin or OpenPets MCP tools
  -> @open-pets/client
  -> OpenPets desktop local IPC
  -> default pet or selected agent pet

No configured pet: use the desktop default pet.
Configured installed pet: use an explicit agent pet lease.
Missing, invalid, or broken pet: fall back to the default pet.
Lease close or expiry: agent pet window closes when the last lease ends.

Safety and behavior

OpenCode integration is fire-and-forget. It should not slow down OpenCode or change OpenCode behavior if OpenPets is closed.

Protection	Behavior
Feedback loops	OpenPets MCP tools are ignored by the plugin event mapper.
Speech cooldown	Normal and error speech are throttled.
Permission speech	Permission messages use their own shorter cooldown.
Repeated reactions	Same reaction is suppressed briefly to avoid spam.
Debug logs	Paths and secret-like values are sanitized.
Config edits	Atomic writes, backups, permission checks, symlink rejection, and size limits.

Troubleshooting

OpenCode does not react

Confirm the OpenPets desktop app is running.
Restart OpenCode after changing plugin or MCP configuration.
Check that your global or project OpenCode config includes the OpenPets plugin and MCP server.
Use the desktop detail page Refresh action to re-check global setup.

Status says custom or conflict

Review the OpenCode config before forcing an update. Keep your own notes outside OPENPETS:START and OPENPETS:END so OpenPets can safely refresh its managed block.

The wrong pet appears

Re-run setup with the pet ID you want. If that pet is not installed, invalid, or broken, the desktop app falls back to the default pet.

Refresh project setupbash

npx -y @open-pets/cli@latest configure --agent opencode --pet <pet-id> --cwd . --force