Tool Audit

Each plugin is its own package — install only what you want and register its directory:

CFG="$HOME/.config/opencode"
mkdir -p "$CFG/toolbox" && cd "$CFG/toolbox"
npm init -y >/dev/null 2>&1
npm install @bandonker/opencode-memory

Then add "$CFG/toolbox/node_modules/@bandonker/opencode-memory" to the plugins array in opencode.jsonc and reload.

Clone the repo and build the packages locally — same layout npm install produces, useful for development or offline installs:

git clone https://github.com/Bandonker/open-toolbox.git
cd open-toolbox
npm install
npm run build:packages        # emits packages/<name>/ (package.json + index.js)

CFG="$HOME/.config/opencode"
mkdir -p "$CFG/toolbox"
cp -r packages/* "$CFG/toolbox/"
(cd "$CFG/toolbox" && npm install)

Then register with the same node -e snippet above (it scans toolbox/node_modules/@bandonker/), and reload.

npm install works identically on Windows — run the first snippet in PowerShell (with $CFG = "$HOME\.config\opencode"), or in WSL/Git Bash unchanged. Registering the plugins array uses the same node -e snippet — it relies on os.homedir() and path.join(), so it is platform-neutral. Note that a backslashed path in JSON must be escaped (C:\\path\\to); the snippet emits forward slashes, which opencode accepts on Windows.

Same packages, but under <repo>/.opencode/toolbox/ instead of $HOME/.config/opencode/toolbox/, and registered in the project opencode.jsonc rather than the global one:

mkdir -p .opencode/toolbox && cd .opencode/toolbox
npm init -y >/dev/null 2>&1
npm install @bandonker/opencode-sessions @bandonker/opencode-memory

Two independent reasons, both of which make the flat layout fail:

1. Resolution. opencode v2 auto-discovers loose .ts files under plugins/, but does not resolve bare npm specifiers from the config directory for them. A plugin that does import { Plugin } from "@opencode/plugin" fails to load with Cannot find package '@opencode/plugin'. Registered as a package directory, it resolves normally.
2. The loader treats every export as a plugin factory. A stray helper export in plugins/ fails the load with prompt.split is not a function and cascades into config/provider errors. Keeping helpers in their own files outside plugins/ avoids that entirely.

Because resolution is anchored at the package directory, not hoisted to the config root. A single npm install in toolbox/ populates the shared copy; the per-package symlink is what makes it reachable from each plugin. This is the same layout pnpm uses.

Spawn child sessions, wait for their results, send follow-ups, answer permission prompts, cancel them, and hand off the current working point into a fresh session. Created sessions are real opencode sessions and appear in the Desktop session switcher.

It also adds project presence: any session working in a repo can see the other sessions in that repo — including ones this plugin did not spawn — and can message them. opencode has no session.list(), so peers are discovered from the server-wide event stream and announced by each session on its first turn.

The brief injected into each request is targeted, not a roster: a session is told about a peer only when that peer could affect its work — it holds a file this session is writing, it is in this session's lineage, it is mid-turn, or it declared overlapping work. When nothing is relevant, nothing is injected. With fileLocks: "enforce" two agents about to write the same file don't just get told to take turns — the write actually waits for the holder, and fails loudly naming who has it if the wait runs out. A peer that has gone quiet is verified with session.get rather than assumed dead, and a session you closed or deleted is confirmed absent and dropped from the list instead of lingering as a ghost.

Tools: 9. See the opencode-sessions package documentation for the complete tool list and configuration knobs.

Record architectural decisions with context and consequences, then search and update them from a local SQLite FTS5 database.

Tools: decision_log, decision_search, decision_list, decision_get, and decision_update.

Log errors with context, search previous failures, and record resolutions so recurring problems do not have to be debugged from scratch.

Tools: 5, including error logging, search, listing, and resolution tracking.

Save reusable code snippets locally and search them by language, tags, or full text. Everything is stored locally in SQLite with full-text search.

Tools: 5 for saving, retrieving, listing, updating, and searching snippets.

Index a codebase directory and run BM25-ranked full-text search over it. The index is local and can be refreshed incrementally as the project changes.

Tools: 4 for indexing, searching, inspecting status, and managing the index.

Record every tool call with its tool name, arguments, status, duration, and error. Use trace_query to search the audit log, trace_stats to summarise it, and trace_export to export it. Secrets in arguments are redacted before they touch disk.

Tools: trace_query, trace_stats, and trace_export.

Options

Each option is read from the plugin options object (npm installs) or the env var (always works):

Values are read when the plugin loads, so restart opencode after changing them. opencode-sessions has its own knobs — see its README.

Registers slash commands for the most common toolbox actions, including /handoff, /decide, /journal, /recall, /index, /trace, /toolbox, and /stats.

See Commands for the command list. Commands inject short instructions into the current session and use the corresponding toolbox tools.

Trims stale tool output from the outgoing request only. The session transcript on disk is unchanged, and pruned tool output can be recalled or re-run. The planner preserves a stable prompt-cache prefix, removes superseded output, and can proactively summarise stale context before the model window fills.

Use context_pruner_stats to inspect savings, context_report to inspect the active budget and epoch, and context_pruner_recall to retrieve pruned output without re-running the original tool.

Options

context-pruner is a context compiler: it trims stale tool output from the outgoing request only. The session transcript on disk is unchanged, and a pruned tool can simply be re-run.

It measures tokens (calibrated against provider usage), plans prune changes once per epoch, and reuses those decisions verbatim so the prompt-cache prefix stays stable between replans. By default it also keeps the outgoing request near a steady ceiling well below the model window (steadyTargetRatio, default 0.06), so stale closed topics are summarised before the window ever fills; set proactiveSummarize: false or steadyTargetRatio: 0 for window-only behaviour. Without a resolvable window it falls back to the positional rules below.

On top of that it removes output that is provably superseded (a newer read or write of the same file), and over the target it summarises the largest stale units — tool output and, since prose is on by default, assistant/user text — with the session model automatically, so savings land even when the model ignores nudges. It reads optional config from .opencode/context-pruner.jsonc (project) then ~/.config/opencode/context-pruner.jsonc (global), and can also read a DCP dcp.jsonc for migration.

Session-scoped state and the digests a session produced are reclaimed when the host reports session.deleted, with a startup sweep covering sessions deleted while opencode was closed. The non-session digest/calibration caches are capped by count (storageGc).

Export session transcripts to Markdown, JSON, JSONL, or text with a model and usage header. Exports support role and tool filters, optional reasoning, per-part truncation, secret redaction, and safe non-overwriting filenames.

session_export writes a file or returns the export inline; session_export_info reports the current configuration and last export.

Options

Store and recall durable local memories without an embedding API, cloud service, or network request. Relevant memories are injected into each request within a character budget and deduplicated per session.

Tools: memory_remember, memory_recall, memory_forget, memory_list, and memory_stats. The database lives at ~/.opencode-plugins/memory/memory.db.

Options

Start an objective with /goal <objective> and optional - success criteria. The goal is re-injected into requests and the model is automatically continued when a turn ends, until goal_complete, goal_blocked, an interrupt, a stall, repeated failures, or the iteration/time budget stops it.

Goal state is persisted per session, so it survives plugin reloads and long turns. Tools: goal_complete, goal_blocked, and goal_progress.

Options

The loop. /goal Ship the login fix stores the objective and starts a normal turn. Follow it with - lines to list success criteria. The objective is re-injected into every request, so it survives long turns and compaction; when a turn ends (session.idle/session.execution.succeeded) the plugin queues a continuation prompt carrying the objective and the remaining budget. It stops when the model calls goal_complete (which requires concrete evidence unless requireEvidence is off) or goal_blocked, when you interrupt a turn (the goal pauses rather than fighting you), when stallLimit turns run no tools and the reply is unchanged, after maxFailures consecutive execution errors, or when the iteration/time budget is exhausted. Goal state is persisted per session, so a paused or budget-stopped goal can be resumed with /goal resume.

Detect and redact secrets across outbound HTTP bodies, prompts, tool arguments and results, and child-process environments. Choose observe, redact, or block mode, with high-precision rules, entropy fallback detection, allowlists, and a hashed JSONL audit that never stores the secret value.

Tools: secret_shield_scan, secret_shield_stats, secret_shield_shape, and secret_shield_keys.

Options

Normalise OpenAI-compatible SSE streams when a content, reasoning, or tool delta arrives after the provider's finish_reason chunk. This prevents invalid provider-output failures and the follow-on failed-session-drain cascade for reasoning models behind strict gateways.

Options

Strips the <available_skills> catalog from the system prompt to save tokens. The skill tool remains available on demand, so agents can still load a skill when they need it.

Track lifetime tokens, cost, tool calls, model usage, and background title or compaction spend in local SQLite. Use stats_summary, stats_tools, stats_tokens, stats_heatmap, or /stats for the data, and stats_dashboard to write a self-contained HTML dashboard.

The dashboard includes an activity heatmap, a 30-day token chart, tool and model tables, exact hover breakdowns for daily activity and chart bars, searchable multi-select model filtering, responsive layout, and automatic refresh without spending model tokens.

Options

Dashboard screenshots

Cost is computed from the provider's real price list. The plugin reads each model's published per-million-token rates via ctx.model.list() and shows both reported (what opencode billed) and list price (API-equivalent) — so free models show $0.00, unpriced ones show — (never a fake zero), and flat-rate subscriptions still show what the usage was worth. Local models have no published price; give them one with prices, e.g. OPENCODE_USAGE_STATS_PRICES={"lmstudio/qwen3-coder":{"input":0,"output":0,"cache":{"read":0,"write":0}}}. Token counts, tool calls and the heatmap are captured for every model regardless of pricing.

The plugin API has no way to add a Settings tab, so /stats opens the dashboard for you directly from the server process — it never calls the model. Set OPENCODE_USAGE_STATS_OPEN=true to open it automatically at startup, or OPENCODE_USAGE_STATS_NO_OPEN=1 to suppress browser launches (headless).

Note: https://opencode.ai/config.json describes the TUI's settings, not the server config. The server validates a plugins (plural) array — that is the key the runtime reads, confirmed in the server log when the config is reloaded.

The loose-file layout is the cause. If you copied plugins/*.ts into ~/.config/opencode/plugins/, opencode v2 will discover those files but cannot resolve their npm imports from the config directory, so every plugin fails identically.

Fix: install the built packages and register them instead. See Quick start. Remove the old loose files afterwards — leaving them in place produces a load error per plugin per reload:

rm -rf ~/.config/opencode/plugins

A helper file ended up inside plugins/. opencode treats every export of a file under plugins/ as a plugin factory, so a stray helper export breaks the load. The package layout avoids this by construction; if you are on the flat layout, move lib/ and opencode-sessions/ out of plugins/ and restart.

1. npm run build:packages actually produced packages/<name>/package.json.
2. toolbox/node_modules exists (one npm install at the toolbox/ level).
3. Every toolbox/<name>/node_modules symlink exists.
4. The absolute paths in the plugins array of opencode.jsonc are the package directories, not the .ts files.
5. You reloaded (opencode reload) or restarted — a reload is required, and for a fresh install a full restart is safer.

Confirm what opencode actually registered:

opencode plugin list

opencode plugin list reports the configured plugin paths, including ones that failed to load. To verify a plugin truly loaded, check the log for loading plugin and confirm there is no matching failed to load plugin:

grep -E 'loading plugin|failed to load plugin' ~/.local/share/opencode/log/opencode.log | tail

Third-party packages are often still v1-only. A v1 plugin depends on @opencode-ai/plugin and/or exports Plugin differently, and will fail under v2. Check its package.json for a dependency on @opencode/plugin (v2) versus @opencode-ai/plugin (v1), and confirm the release you are installing predates the v2 migration, before adding it to the plugins array.