opencode-config/USAGE.md

Usage Guide — Plugins & MCP Servers

Reference for every plugin and MCP server shipped in opencode.json.template. Versions reflect what was installed when this doc was written; @latest packages update on their own.

• Plugins load at opencode startup and hook into the agent loop. Most work automatically; a few add slash commands or tools you call explicitly.
• MCP servers are external processes opencode talks to over the Model Context Protocol. Each exposes tools the agent can call. Toggle one with "enabled": true|false in its mcp block.

Diagnostic: if opencode hangs on startup, run opencode run --pure "ok" to start without any external plugins and isolate the culprit.

---

Plugins

oh-my-openagent (oh-my-openagent, v4.10.0)

Batteries-included agent harness: multi-model orchestration, parallel background agents, extra LSP/AST tools, plus modes and slash commands (ultrawork, search, analyze, team, hyperplan).

• Use: mostly automatic once loaded; its modes/slash commands appear in the TUI.
• Note: the heaviest plugin here — it registers many agents and lifecycle hooks. Read its own README for the full mode/command matrix before relying on Team Mode etc.

opencode-mem (opencode-mem, v2.17.1)

Persistent memory for the agent backed by a local vector database. Auto-captures salient facts across sessions and retrieves them on later runs.

• Use: automatic capture + recall. Memory scope and auto-capture are configurable (see the plugin's "Configuration Essentials").
• Prerequisite: none external — it routes embedding/LLM calls through opencode's own session API, so whatever provider you configured "just works." Stores data locally.

opencode-pty (opencode-pty, v0.3.4)

Interactive pseudo-terminal management — run background / long-running processes (dev servers, REPLs), send input, and read output with regex filtering. Fills the gap left by the synchronous built-in bash tool.

• Tools: pty_spawn (+ companions to write/read/kill sessions).
• Slash commands: e.g. /pty-open-background-spy opens a web UI to watch sessions.
• Use: ask the agent to start a server/process in a PTY instead of blocking bash.

@tarquinen/opencode-dcp — Dynamic Context Pruning (v3.1.12)

Optimizes token usage by pruning obsolete tool outputs from the conversation context as it grows.

• Use: fully automatic; no commands. Reduces token spend on long sessions.

opencode-command-inject (opencode-command-inject, v1.3.0)

At startup, auto-injects project commands the agent can run: Makefile targets, package.json scripts, and discovered local skills.

• Use: automatic per project — open opencode in a repo and its build/test/run commands become available to the agent.

opencode-notify (opencode-notify, v0.3.1)

Native system popups with action buttons for permission requests (Accept/Always/Reject/Dismiss) and questions (View/Dismiss).

• Use: automatic.
• Prerequisite (Linux): a desktop notification daemon — libnotify/notify-send (Debian/Ubuntu: libnotify-bin, Fedora: libnotify).

@gotgenes/opencode-agent-identity (v3.1.1)

Gives agents a self-identity and adds per-message agent attribution so you can tell which agent produced which message.

• Use: automatic; surfaces attribution in the transcript.

@ramtinj95/opencode-tokenscope (v1.7.1)

Detailed token-usage analysis — breakdowns by category, visual charts, and subagent cost tracking.

• Use: runs as a tool. To expose it as a slash command, create ~/.config/opencode/command/tokenscope.md containing Call the tokenscope tool directly without delegating to other agents., then restart opencode and run /tokenscope.

opencode-rag-plugin — REMOVED

Local-first semantic code search (vector index over your codebase). Not enabled because its startup probes a local embedding backend (Ollama on localhost:11434 by default) with no timeout — if the backend is down, opencode hangs after loading plugins. To re-enable: start a backend (ollama serve + ollama pull embeddinggemma, or configure an OpenAI/Cohere embedding key), then add "opencode-rag-plugin" back to the plugin array.

---

MCP Servers

Each entry: what it gives the agent · prerequisites. Set "enabled": false to turn one off without deleting it.

git — git-mcp-server (enabled)

Git repository operations: status, diff, log, branch, stage, commit, etc., as tools.

• Prerequisite: the git-mcp-server binary on PATH (Python: pip install mcp-server-git, or the npm equivalent). Plain git must be installed.

filesystem — mcp-server-filesystem ${PROJECTS_PATH} (enabled)

Sandboxed file read/write/list, scoped to your projects directory (${PROJECTS_PATH}, defaults ~/projects). Lets the agent operate on files outside the current cwd safely.

• Prerequisite: @modelcontextprotocol/server-filesystem. Adjust the path to widen/narrow access.

jina — jina-mcp-tools (enabled)

Jina AI tooling: clean webpage reading, web search, and embeddings via Jina's Reader/Search APIs.

• Prerequisite: jina-mcp-tools; a Jina API key may be needed for higher rate limits.

codegraph — codegraph serve --mcp (enabled)

Semantic code-graph navigation across a codebase (symbols, references, structure).

• Prerequisite: npm i -g @colbymchenry/codegraph, then run codegraph init once per project.

smart-tree — st --mcp (enabled)

Fast directory-tree / codebase overview for quickly orienting in a repo.

• Prerequisite: the st binary at ~/.local/bin/st.

dbhub — dbhub --transport stdio --demo (disabled)

Universal database gateway — query SQL databases through MCP. Shipped in demo mode and disabled by default.

• Use: set "enabled": true and point it at a real database to query your data.

memory — @modelcontextprotocol/server-memory (enabled)

Knowledge-graph persistent memory (entities/relations) the agent can read and write across sessions. Distinct from opencode-mem (this is the official MCP variant).

• Prerequisite: none (runs via npx -y).

playwright — @playwright/mcp@latest (enabled)

Browser automation: navigate, click, fill forms, screenshot, scrape — driven by Playwright.

• Prerequisite: Playwright browsers download on first use (npx playwright install if needed).

chrome-devtools — chrome-devtools-mcp (enabled)

Drive Chrome via the DevTools protocol: inspect the DOM, capture performance traces, read console/network. Good for debugging live pages.

• Prerequisite: the chrome-devtools-mcp binary and a Chrome/Chromium install.

github — @modelcontextprotocol/server-github (enabled)

GitHub API access: repos, issues, pull requests, search, file contents.

• Prerequisite: a GitHub token (GITHUB_TOKEN / GITHUB_PERSONAL_ACCESS_TOKEN) for private repos and write actions.

context7 — @upstash/context7-mcp@latest (enabled)

Injects up-to-date, version-correct library documentation into context on demand — ask "use context7" when you need current API docs for a package.

• Prerequisite: none (runs via npx -y).

exa — mcp-remote https://mcp.exa.ai/mcp (enabled)

Exa neural web search — semantic search over the web, returning relevant pages/snippets.

• Prerequisite: network access to mcp.exa.ai; an Exa key may be required for higher limits.

sequential-thinking — @modelcontextprotocol/server-sequential-thinking (enabled)

A structured step-by-step reasoning tool the agent uses to break hard problems into explicit, revisable thought steps.

• Prerequisite: none (runs via npx -y).

brave-search — @brave/brave-search-mcp-server (enabled)

Web and local search via the Brave Search API.

• Prerequisite: BRAVE_API_KEY env var. Without it, disable this server (see install notes).

---

Enabling / disabling

In ~/.config/opencode/opencode.json:

• MCP server: flip "enabled": true|false inside its block under "mcp".
• Plugin: add/remove its package name from the top-level "plugin" array (there is no per-plugin enabled flag — presence in the array = on).

Restart opencode after changes. Validate syntax with python -m json.tool ~/.config/opencode/opencode.json.