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`.