Code Review

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

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

git clone https://github.com/bandonker/open-toolbox.git
cd open-toolbox
npm install                  # build, link, install runtime deps, write opencode.jsonc

That is the whole install. npm install runs prepare, which builds the packages, links them into $HOME/.config/opencode/toolbox/, installs the @opencode/plugin runtime there, applies the exports patch the v2 loader needs on Linux, and registers every plugin in opencode.jsonc. Nothing is hardcoded: the repo location comes from the clone, the toolbox from $HOME.

It is safe to run repeatedly — a second npm install on an already-set-up machine changes nothing. If it ever needs re-doing by hand:

npm run setup                # the same, without reinstalling dependencies
npm run deploy:check         # report toolbox drift, change nothing

Register with the same node -e snippet above, then reload.

Run the install snippet in PowerShell (with $CFG = "$HOME\.config\opencode"), or in WSL/Git Bash unchanged. The registration snippet uses os.homedir() and path.join() so it is platform-neutral. Backslashed paths 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/, registered in the project opencode.jsonc:

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

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

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 makes it reachable from each plugin. 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.

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

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

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, goal_progress.

Options

The loop. /goal Ship the login fix stores the objective and starts a normal turn. Follow it with dash-prefixed lines to list success criteria. The objective is re-injected into every request, so it survives long turns and compaction; when a turn ends 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. A paused or budget-stopped goal can be resumed with /goal resume.

/plan <task> walks a task through a real planning phase: the agent researches the task, asks clarifying questions, and writes a phased plan annotated with risks, success criteria, time and cost estimates, and research notes. Execution then spawns one child session per step — free models first, paid as fallback — with parallel children capped and progress tracked per project; /plan status shows the live board.

Plan state is tracked in-plugin per project and session and exposed to the model as 37 tools (plan plus 36 plan_* helpers), including plan_add_step, plan_add_risk, plan_add_criterion, plan_add_research, plan_progress, plan_checkpoint, plan_approve_phase, plan_rollback, plan_spawn_child, plan_metrics, plan_cost_optimize, plan_test_strategy, plan_time_estimate, plan_generate_docs — and plan_link_decision, plan_link_error, plan_link_snippet to tie the plan into the decision log, error journal, and snippet library.

Options

/deep-research <topic> fans the topic out across a taxonomy of research angles as parallel child sessions (bounded by maxConcurrent), then iterates: it reads what the agents report, finds the gaps, and dispatches follow-up questions with deep_research_deliberate, recording the agents' answers with deep_research_answer. deep_research_consolidate merges the findings and the deliberation Q&A into one deduplicated, conflict-flagged report.md inside the topic folder; deep_research_runs lists past runs and their report paths. History lives in local SQLite.

Tools: deep_research, deep_research_deliberate, deep_research_answer, deep_research_consolidate, deep_research_write_report, deep_research_runs.

Options

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

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

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, decision_update.

Options

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

Tools: error_log, error_search, error_list, error_resolve, error_delete.

Options

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: snippet_save, snippet_get, snippet_list, snippet_search, snippet_delete.

Options

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: codebase_index, codebase_search, codebase_index_status, codebase_delete_index.

Options

Record every tool call with its tool name, arguments, status, duration, and error. Secrets in arguments are redacted before they touch disk.

Tools: trace_query, trace_stats, trace_export.

Options

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, memory_stats. The database lives at ~/.opencode-plugins/memory/memory.db.

Options

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, 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}}}.

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.

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.

How it works

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

Options

Full reference: See the options table below — 50+ options organised by category.

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.

Options

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, 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 AI.Error.InvalidProviderOutput: OpenAI Chat received content after the finish reason and the follow-on Failed to drain Session cascade for reasoning models behind strict gateways.

A stream the gateway cuts mid-generation (content in hand, no finish reason) is deliberately left unterminated rather than closed with an invented finish_reason. A fabricated "stop" would mark the turn as a clean completion, hiding the cut and suppressing opencode's own recovery — an incomplete stream is a retryable error, so the turn is re-attempted and continued instead of silently keeping truncated text. Cuts are counted in finish_guard_stats (truncated) and the payloads immediately before the cut are dumped to the capture file.

Options

Tools: finish_guard_test (run the SSE transform on a sample payload), finish_guard_stats (observed stream metrics — normalised, truncated, retries).

Weak or free models sometimes degenerate into repetition — the same tool call, or the same assistant reply, over and over — until the user aborts. The goal plugin has a stall detector, but it only runs while a /goal is active; an ordinary build/explore/general session has no guard.

loop-guard watches every tool call and every outgoing request. It counts consecutive identical tool calls (tool name plus a stable stringification of the input, so key order does not matter) and consecutive identical assistant replies (text and reasoning plus any tool calls). Any different call or reply resets the run, so legitimate re-reads spread across a long session never trip it. At repeatLimit it injects a system nudge telling the model to change approach or conclude; if the run continues to cancelLimit it calls session.interrupt to cancel the turn.

Options

Reviews files, diffs, and whole projects for security vulnerabilities, code smells, and type-safety issues. A static pass runs first; when it finds fewer than llmFallbackThreshold findings, a free-LLM pass fills in the gaps. Reviews and custom rules live in a local SQLite FTS5 database, so history, search, per-category stats, and trend analysis accumulate over time.

With enableAgentFixes on, findings are handed to fixer subagents (at most maxFixAgents at once); code_review_fix returns the suggested patch for one finding.

Commands: /code-review file <path>, /code-review diff, /code-review project [path], /code-review fix-all [reviewId], /code-review deep [path], /deep-code-review [path].

Tools (11): code_review_file, code_review_diff, code_review_project, code_review_history, code_review_get, code_review_search, code_review_stats, code_review_trends, code_review_fix, code_review_custom_rules, code_review_config.

Options

More knobs: per-category rule toggles (rules.security, rules.bugs, rules.style, rules.performance), focusAreas, severity and severityOverrides, includePatterns / excludePatterns, file and finding caps (maxFiles 50, maxFindingsPerFile 20), and the enableTrendAnalysis / enableConfidenceScoring toggles.

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:

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.

Fix: the package layout avoids this by construction. If you are on the flat layout, move lib/ and opencode-sessions/ out of plugins/ and restart.

Check each of these in order:

1. npm run setup completed (packages/<name>/package.json exists).
2. toolbox/node_modules exists.
3. Every toolbox/<name>/ resolves (a symlink in link mode).
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.

If any of those are wrong, npm run setup repairs all of them.

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:

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.

Fix: 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.

1. Check context_pruner_stats — if it shows no prunes, the plugin may not be loaded.
2. Verify enabled is true and OPENCODE_CONTEXT_PRUNER_ENABLED is not set to false.
3. Check that minChars (default 2000) is not higher than most of your tool outputs.
4. Set log: true to see prune decisions on stderr.

1. Switch to observe mode to audit without blocking: OPENCODE_SECRET_SHIELD_MODE=observe.
2. Use the allow option to whitelist specific patterns: OPENCODE_SECRET_SHIELD_ALLOW="/my-safe-token/".
3. Check secret_shield_stats for what is being detected.

The SQLite databases are stored in ~/.local/share/opencode/. Ensure your user has write access to this directory:

chmod -R u+w ~/.local/share/opencode/

Check the OpenCode Desktop logs for error messages. Common causes:

• Missing environment variables
• Incompatible Node.js/Bun version
• Corrupted plugin state (try deleting the plugin's state directory)

Check that:

• The goal is not paused (/goal resume to resume)
• The iteration/time budget has not been exhausted
• The model is calling goal_complete or goal_blocked

No. This pack requires opencode v2. The plugin loader, hook APIs, and package resolution model are all v2-specific.

Yes. Each plugin is an independent npm package. Install only what you need and register just those directories in opencode.jsonc.

All SQLite databases live under ~/.opencode-plugins/ (or the directory specified by each plugin's dir option). No data leaves your machine.

Every plugin has an enabled option (default true). Set it to false in the plugin's options object or via its env var, then reload opencode.

Context management is inherently complex — token estimation, cache awareness, summarisation strategy, and recovery behaviour all need tuning. The defaults work well for most users; the options are there for edge cases. See the Context Pruner section above for the full reference.

All plugin data is stored locally under ~/.opencode-plugins/. To back up your data:

cp -r ~/.opencode-plugins/ ~/backup-opencode-plugins/

To restore:

cp -r ~/backup-opencode-plugins/ ~/.opencode-plugins/

Uninstalling a plugin removes its code but does not delete its data. Your SQLite databases and configuration remain in ~/.opencode-plugins/. To fully remove a plugin and its data:

npm uninstall @bandonker/opencode-<plugin-name>
rm -rf ~/.opencode-plugins/<plugin-name>/

Most plugins have negligible overhead. The context pruner runs only when token usage exceeds the threshold, and the usage stats plugin samples periodically. The goal loop adds minimal overhead — it only re-injects the objective into requests and checks for continuation conditions.

No. These plugins are designed specifically for OpenCode Desktop and rely on its plugin API, hook system, and package resolution model. They are not compatible with other AI coding tools.