Skip to content

Platforms

Pantheon runs only on OpenCode. Multi-platform adapters were removed in v1.0; Claude Code, Cursor, Windsurf, Cline, Continue.dev, and VS Code Copilot are not supported. This page is an overview and links out. It does not restate the support matrix — that is Compatibility.

Form factors

OpenCode ships as a terminal TUI, a desktop app, and an IDE extension. Pantheon's agents, skills, and instructions are discovered from the project directory the same way in each. The desktop app adds integrated diffs, file-tree browsing, and native notifications; it is not a separate installation model.

Install

Use the installer, not manual copying:

npx pantheon-opencode init            # global
npx pantheon-opencode init --project  # project-local

The installer registers Pantheon's runtime integrations automatically. It writes the singular plugin key for OpenCode V1 and the plural plugins key for OpenCode V2; do not add either key by hand. Flags, backup, uninstall, and reconcile are in Installation.

Configuration

OpenCode reads opencode.json (or opencode.jsonc) from the project root. The installer writes opencode.json; a V2 host may also merge a sibling .jsonc — see Compatibility.

default_agent: zeus and permission.skill are seeded by the installer, not shipped as a template file. The published package carries no opencode.json template. Contributors who keep a project-level config for their own sessions should leave it untracked.

Agent definitions live in src/agents/*.md; the installer copies them into the selected config tree. Editing an installed copy does not persist — the next init overwrites it. Edit the canonical source instead.

File locations

Project install:

your-project/
├── opencode.json
├── AGENTS.md
├── .opencode/agents/
├── .opencode/skills/
├── .opencode/instructions/
├── .opencode/prompts/
└── .pantheon/

Global install:

~/.config/opencode/
├── opencode.json
├── AGENTS.md
├── agents/
├── skills/
├── instructions/
├── scripts/          # installed MCP entrypoints
└── tui.json          # V1 TUI registration

The V2 TUI uses a local plugin directory instead of tui.json. See OpenCode 2.x.

Quick reference

Action Command
Start OpenCode (TUI) opencode
Run non-interactively opencode run "prompt"
Initialize project rules /init in-session
Invoke an agent @zeus: implement email verification
List agents opencode agent list
List models opencode models
Add an MCP server opencode mcp add
Add a provider key opencode auth login
List sessions opencode session list
Token stats opencode stats

/init is OpenCode's built-in project-context generator. It is complementary to Pantheon: /init captures project-level conventions, while Pantheon agents supply role behavior. If AGENTS.md already exists, /init improves it in place.

ACP (Agent Client Protocol)

OpenCode can run as an ACP-compatible agent for editors such as Zed, JetBrains, or Neovim. Start the server with opencode acp; it communicates over JSON-RPC on stdio. ACP does not change the selected plugin contract: V1 hook/delegate behavior still depends on V1 host events, and the V2 plugin remains its own surface. Verify the registration in opencode.json before relying on a feature.

For Zed, add this to ~/.config/zed/settings.json:

{
  "agent_servers": {
    "OpenCode": {
      "type": "custom",
      "command": "opencode",
      "args": ["acp"]
    }
  }
}

type: "custom" is the field Zed's settings schema uses for a hand-configured agent server rather than a built-in one.

Troubleshooting

Symptom Check
Agents not showing up opencode agent list; valid YAML frontmatter; correct agents directory
Default agent not working default_agent must match an agent with mode: primary
Model not available provider/model format; opencode models; provider key
Instructions not loading Paths are relative to the config file; global and project layers merge
MCP server not connecting opencode mcp list; OAuth via opencode mcp auth <server>
Skills not discovered permission.skill allows the skill; skills are installed
Slow responses Cheaper model for discovery; fewer instruction files

For MCP-specific failures, see MCP. For installer and driver problems, see Installation.

Dynamic prompts

OpenCode prompt files support {file:path} interpolation. Pantheon's /pantheon council prompt uses that to build a dynamic, per-run prompt. The generation script and its limits are described in the prompt file itself (prompts/); static prompt templates remain the default for the other commands.