From ab7c909dc8fda3d71ba740d25f43715025822536 Mon Sep 17 00:00:00 2001 From: chaos Date: Mon, 15 Jun 2026 23:13:23 +0800 Subject: [PATCH] Add USAGE.md: per-plugin and per-MCP usage guide Documents what each of the 8 plugins and 14 MCP servers does, how to use it (auto vs slash commands/tools), and prerequisites. Links it from the README and adds enable/disable instructions. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 9 ++- USAGE.md | 164 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 172 insertions(+), 1 deletion(-) create mode 100644 USAGE.md diff --git a/README.md b/README.md index 52eabd9..6fe45eb 100644 --- a/README.md +++ b/README.md @@ -72,6 +72,11 @@ echo 'export BRAVE_API_KEY=BSA...' >> ~/.bashrc - **14 MCP Servers** - codegraph, brave-search, playwright, github, context7, exa, etc. - **Model Config** - Kimi K2.6 + 14 other models via `@ai-sdk/openai-compatible` +## Usage + +See **[USAGE.md](USAGE.md)** for what every plugin and MCP server does, how to use it, +and its prerequisites — plus how to enable/disable each one. + ## Updating ```bash @@ -114,6 +119,7 @@ git pull ``` opencode-config/ ├── opencode.json.template # Config template with placeholders +├── USAGE.md # Per-plugin & per-MCP usage guide ├── agents/ # Agent definitions │ ├── explorer.md │ ├── reviewer.md @@ -124,5 +130,6 @@ opencode-config/ │ └── ... ├── install.ps1 # Windows installer ├── install.sh # macOS/Linux installer -└── README.md +├── README.md +└── USAGE.md ``` diff --git a/USAGE.md b/USAGE.md new file mode 100644 index 0000000..3b26b45 --- /dev/null +++ b/USAGE.md @@ -0,0 +1,164 @@ +# 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`.