opencode-bytheway

OpenCode plugin that adds temporary "by the way" side-session workflows.

Quick notes on Installation / Upgrade

opencode-bytheway supports both OpenCode V1 (opencode) and OpenCode V2 (opencode2) from the same npm package. The hosts use separate TUI configuration files and automatically select the matching runtime implementation from the shared ./tui entrypoint.

OpenCode V1

Install or upgrade with OpenCode's plugin installer:

opencode plugin [email protected] --global --force

• use this method because tagging @latest does not update, it's a one-shot meaning of 'latest' (by intention of opencode)

• Restart or reload OpenCode after updating so the TUI plugin is reloaded.

OpenCode V2

Install with OpenCode V2's plugin installer:

opencode2 plugin add [email protected]

The package exposes only ./tui, so V2 installs it as a TUI plugin and adds it to the plugins array in ~/.config/opencode/cli.json. Restart opencode2 after installing or changing the package version.

If 0.8.0 was previously installed with opencode2 plugin add, remove its incorrectly classified server entry before installing 0.8.1:

opencode2 plugin remove [email protected]
opencode2 plugin add [email protected]

Keep V1 and V2 working side by side

V1 and V2 can use the same opencode-bytheway release at the same time. They read different global TUI configuration files and select different runtime implementations from the package's ./tui export:

• V1 (opencode) reads ~/.config/opencode/tui.json or tui.jsonc and uses plugin.
• V2 (opencode2) reads ~/.config/opencode/cli.json and uses plugins.

Pin the same package version in both files. For example, use this for V1 in ~/.config/opencode/tui.jsonc:

{
  "plugin": ["[email protected]"]
}

And use this for V2 in ~/.config/opencode/cli.json:

{
  "plugins": ["[email protected]"]
}

Keep unrelated settings already present in either file. Installing the V1 entry with opencode plugin ... --global does not replace the V2 cli.json entry; likewise, changing cli.json does not configure V1.

If cli.json does not exist when V2 first starts, V2 may create it by migrating supported settings from the global V1 tui.json and legacy TUI state. It leaves the V1 files unchanged so both versions can continue to run. This migration happens only once, so after cli.json exists, make subsequent plugin-version changes in both files when retaining side-by-side support.

Retire the V1 configuration after moving to V2 only

Do this only after V2 is working:

1. Confirm ~/.config/opencode/cli.json contains the opencode-bytheway entry and any TUI settings you still need.
2. Restart opencode2 and run /btw-status, then open and end one side session with /btw and /btw-end.
3. Remove only the opencode-bytheway item from the plugin array in ~/.config/opencode/tui.json or tui.jsonc.
4. Check ~/.config/opencode/opencode.json or opencode.jsonc and remove a stale V1 plugin entry for opencode-bytheway if an older release or installer added one. Current releases are TUI-only and should not be configured there for V1.
5. If the V1 tui.json(c) contains no other plugins or settings you want to keep, archive or delete it. Do not delete it before copying wanted settings into cli.json: V2 does not rerun automatic migration after cli.json has been created.

V1 has no plugin-uninstall subcommand. Removing its config entry disables the plugin; an unused cached package can safely remain. The V2 cli.json entry is independent and continues to load the V2 runtime.

name clash

A plugin package opencode-btw already exists. It is not an attempt to emulate Claude Code 'by the way', it provides persistent steering hints.

Usage

Implements something like Claude Code's "btw" feature. You can branch into a temporary side session, then discard it or merge text back into the parent session when you are done. /btw opens a session that you can exit with /btw-end. /btw your prompt here opens the temp session and sends that prompt there without adding it to the parent transcript. /btw-fast opens a temp session with only recent plain-text context when a full fork would be too slow. /btw-prompt can also be used as /btw-prompt tell me more about foo(); it is experimental. Typed /btw, /btw-fast, /btw-merge, /btw-end, /btw-status, and /btw-prompt commands are handled by the TUI plugin instead of requiring a model call just to dispatch.

Normal usage:

• run /btw and then type in the temp session
• run /btw your prompt here to open the temp session and send an initial prompt there
• run /btw-fast when you want a faster side session with only recent plain-text context

Experimental prompt entrypoint:

• run /btw-prompt your prompt here to open the temp session and hand that prompt to the TUI plugin
• the command is handled in the TUI without an LLM hop
• the TUI plugin forks the current session, switches you into the fork in the same terminal, and sends the initial prompt there without adding it to the parent transcript

No nesting of btw sessions.

Install

For OpenCode V1, use OpenCode's plugin installer:

opencode plugin [email protected] --global

For OpenCode V2, use its plugin installer:

opencode2 plugin add [email protected]

The package is TUI-only. V1 loads its explicit ./tui export from tui.json[c]; V2 adds the same package export to the plugins array in global cli.json.

Recommended update method

Use --force if you need to replace an existing pinned version (including if you used @latest because surprise, this does not update when versions change):

opencode plugin [email protected] --global --force

For V2, remove the previous pinned spec before adding the new one so cli.json contains only one version:

opencode2 plugin remove opencode-bytheway@PREVIOUS_VERSION
opencode2 plugin add [email protected]

OpenCode V1 1.18.22 loads TUI plugins from tui.json[c]. Do not add this package to V1 opencode.json[c]; it does not export a server plugin.

Example tui.jsonc:

{
  "plugin": ["opencode-bytheway"]
}

Optional version pin:

{
  "plugin": ["[email protected]"]
}

Restart OpenCode after installing or updating the plugin.

Troubleshooting:

• if /btw does not appear or does not open a side session, confirm the package is loaded in tui.json[c]
• for V2, run opencode2 plugin list and confirm opencode-bytheway appears under TUI, not as a failed Server plugin
• reload or restart OpenCode after changing TUI config

Optional command-family override:

OPENCODE_BYTHEWAY_COMMAND=aside

With that env var set, the plugin exposes /aside, /aside-fast, /aside-merge, /aside-end, and /aside-status instead of the default /btw command family. The experimental /btw-prompt command stays fixed.

Optional diagnostic logging:

OPENCODE_BYTHEWAY_DIAGNOSTICS=1

When enabled, the plugin writes JSONL diagnostic logs to /tmp/opencode-bytheway-event.log and /tmp/opencode-bytheway-toast.log. These logs are disabled by default.

Commands

• /btw: open a temporary btw side session in the same terminal, preserving context from the current session
• /btw-fast: open a temporary btw side session with only bounded recent plain-text context, avoiding a full session fork
• /btw your prompt here: open the temporary side session and send that prompt inside the forked temp session
• /btw-merge: append plain user/assistant text from the temporary session into the original session as it exists when merge runs, then close the temporary session
• /btw-end: return to the original session as it exists now and remove the temporary btw session without carrying text back
• /btw-status: show whether the TUI plugin is loaded
• /btw-prompt your prompt here: experimental TUI-owned entrypoint that opens a forked temp session and sends the initial prompt there

User experience

• /btw is for branching off in the same terminal while keeping your main session intact
• /btw-merge carries back only plain user/assistant text from the temporary session; tool calls and subagent details are omitted
• /btw-merge asks for confirmation first if the original session continued while the temporary session was active
• V2 admits merged context durably with resume: false; it is consumed when the original session next resumes because V2 has no immediate visible equivalent of V1's noReply
• /btw-end is the clear way back when you want to discard the temporary session without merging text back
• nested btw sessions are blocked to avoid stacked temporary contexts

Local development

bun install --ignore-scripts
bun run build
bun run test
bun run test:integration:v1
bun run test:integration:v2
npm pack --dry-run

For local V1 testing, point tui.json[c] at this repository path after running bun run build.

For local V2 testing, point ~/.config/opencode/cli.json at the built entrypoint:

{
  "plugins": ["file:///home/{USER}/projects/opencode-btw-clean/dist/tui.js"]
}

After changing tui.ts, v1.tsx, or v2.ts, run bun run build again before reopening or reloading OpenCode so the local plugin uses the updated dist/tui.js.

bun run test:integration:v1 launches the real installed opencode TUI inside a pseudo-terminal. bun run test:integration:v2 starts an isolated authenticated V2 server and drives a real opencode2 TUI. Both are intentionally separate from bun run test because they depend on local OpenCode binaries and runtime environments. Set OPENCODE_BTW_OPENCODE_BIN=/absolute/path/to/opencode to run the integration suite against a specific OpenCode binary. Set OPENCODE_BTW_OPENCODE2_BIN=/absolute/path/to/opencode2 for the V2 suite.

OpenCode V1 1.18.22 loads TUI plugins from tui.json[c].

Example tui.json entry for the slash commands:

{
  "plugin": [
    "file:///home/{USER}/projects/opencode-btw-plugin"
  ]
}

Point at the package root, not dist/tui.js directly.

Use an absolute file:// path in the config. Do not rely on ~ or $USER expansion inside tui.json, since config values are not shell-expanded.

Local tui.json[c] files are convenient for faster iteration, but keep them untracked in your clone. Their absolute file:// paths are machine-specific and should not be committed to the package repo.

Investigating /btw-prompt

/btw-prompt is intercepted by the TUI prompt layer, so it does not need a model call just to forward the raw command arguments. It uses the same TUI-owned fork flow as /btw your prompt here.

Changelog

0.8.1

• Publish only the ./tui package entrypoint so opencode2 plugin add installs the package as a V2 TUI plugin instead of misclassifying the package root as a server plugin.
• Keep OpenCode V1 installation on the same explicit ./tui entrypoint and document command-based installation for both runtimes.
• Add package contract coverage for the TUI-only manifest.
• Tested with OpenCode V1 1.18.22 and OpenCode V2 0.0.0-beta-18230.

0.8.0

• Promote the tested dual-runtime release to a stable package version.
• Update V2 TUI slot registration for the current object-based plugin API so /btw commands load again.
• Update the V2 plugin contract dependency and package contract coverage for OpenCode 0.0.0-next-17377.
• Tested with OpenCode V1 1.18.15 and OpenCode V2 0.0.0-next-17377.

0.8.0-beta.5

• Update V2 TUI slot registration for the current object-based plugin API so /btw commands load again.
• Update the V2 plugin contract dependency and package contract coverage for OpenCode 0.0.0-next-17377.
• Tested with OpenCode V1 1.18.15 and OpenCode V2 0.0.0-next-17377.

0.8.0-beta.4

• Stop active OpenCode V1 generation before /btw-end or /btw-merge deletes its temporary session, preventing late writes into a removed session.
• Preserve the temporary session and active plugin state when stopping generation fails so cleanup can be retried safely.
• Tested with OpenCode V1 1.18.15 and OpenCode V2 0.0.0-next-17055.

0.8.0-beta.3

• Preserve complete initial V2 /btw <prompt> exchanges and wait for active generation before merging or ending.
• Scope V2 active state by temporary session and preserve admitted merge payloads for exact retry reconciliation.
• Retain direct-prompt context without a completed assistant response and test merge pagination across a real cursor boundary.
• Show a persistent V2 sidebar indicator while the current session is an active /btw side session.
• Publish prereleases on npm's default latest channel, document simultaneous V1/V2 configuration, and run TypeScript validation in CI.
• Tested with OpenCode V1 1.18.15 and OpenCode V2 0.0.0-next-17055.

0.8.0-beta.2

• Add dual OpenCode V1 and V2 support from the same npm package.
• Keep the existing V1 TUI implementation and add a native V2 implementation using V2 storage, routing, commands, and session APIs.
• Add cursor-safe V2 merge boundaries, synthetic fast-context seeding, and an empty-session fallback.
• Make merge delivery retry-safe and preserve recoverable V2 state across transport and cleanup failures after the temporary session has been recorded.
• Add separate real-runtime V1 and V2 integration suites.
• Tested with OpenCode V1 1.18.15 and OpenCode V2 0.0.0-next-17055.

0.7.0

What's New

• Built against OpenCode 1.17.12.
• Add /btw-fast, which opens a temporary session with only bounded recent plain-text context instead of forking the full source session.
• Show immediate startup toasts for /btw and /btw-fast so long-running opens have visible feedback.
• Avoid copying the latest previous session when /btw or /btw-fast starts without an active session.
• Add fork timing diagnostics for /btw and real-TUI integration coverage for /btw-fast.

0.6.0

• Built against OpenCode 1.17.9.
• Remove the server plugin entry and helper tools; the package is now TUI-only.
• Remove server file-handoff/status compatibility paths from the TUI plugin.
• Update integration smoke tests to load the plugin only through tui.json[c].
• Fix slash autocomplete selection for /btw-end and /btw-merge by letting OpenCode's autocomplete handler own Enter while autocomplete is open.
• Clear stale persisted /btw state when OpenCode resumes directly into a previously temporary session.

0.5.1

• Built against OpenCode 1.17.8.
• Speed up bare /btw opens by skipping the source-message pre-scan.
• Clarify that /btw-end returns to the original session as it exists at return time.
• Ask for confirmation before /btw-merge when the original session advanced while the temporary session was active.
• Add real-TUI integration coverage for bare /btw merge boundaries.

0.5.0

• Built against OpenCode 1.17.8.
• Target OpenCode 1.17.8 command behavior by moving /btw slash dispatch fully into the TUI plugin.
• Stop registering server prompt-command shims for the /btw command family, avoiding duplicate slash autocomplete entries and unsafe display-only server command handling.
• Add real-TUI integration coverage for typed bare /btw.

0.4.1

• Built against OpenCode 1.17.7.
• modernize TUI slash-command registration onto the current keymap layer API
• update session list, fork fallback, temp-session rehydration, and merge tracking for current OpenCode SDK shapes
• tag temporary sessions with plugin metadata and harden prompt/status handoff files
• add TypeScript typecheck coverage and update OpenCode/OpenTUI plugin dependencies

0.4.0

• Built against OpenCode 1.17.7.
• show changelog details in README.md so npmjs.com displays release notes
• clarify documented /btw <prompt> support and plugin-hook dispatch behavior

0.3.16

• Built against OpenCode 1.17.7.
• fix typed /btw <prompt> on OpenCode 1.17.7 without runtime exception flashes or origin transcript pollution
• avoid intercepting Enter for unrelated prompt slash commands such as /sessions
• add regression coverage for real TUI prompt handoff and keybinding behavior

0.3.15

• support OpenCode command hooks that mark slash commands handled through the hook output object

0.3.14

• add regression coverage that /btw continues to fork large source sessions without a fork guard

0.3.13

• share bytheway protocol helpers between the server and TUI plugin halves

0.3.12

• clear stale active /btw state from another origin session before opening a new side session
• add opt-in diagnostics and integration coverage for typed /btw <prompt> handoff flow

0.3.11

• update the TUI command and session flow to work with OpenCode 1.14.48
• add an opt-in integration test that launches a real OpenCode TUI session for /btw coverage

0.3.10

• align CI and release workflows with Bun 1.3.13 to match local verification
• make command-handler tests await command completion instead of depending on scheduler timing

0.3.9

• document opencode plugin opencode-bytheway --global as the primary install path because it updates both server and TUI config files
• keep manual dual-file config instructions as a fallback for users not using the plugin installer

0.3.8

• report both server and TUI plugin versions from /btw-status so mismatched OpenCode config entries are easier to diagnose
• document keeping opencode.jsonc and tui.jsonc pinned to the same plugin version

0.3.7

• restore typed /btw, /btw-merge, and /btw-end dispatch for current OpenCode by routing server slash shims into the TUI command handlers
• avoid duplicate slash autocomplete entries by keeping slash metadata on the server shims only
• make /btw-status use the current TUI toast event path
• resume or clear stale /btw state instead of refusing to open a side session after restart
• support /btw <prompt> by handing the inline prompt to the new temporary session

0.3.6

• keep /btw and /btw-prompt visible on the origin session even while a temporary /btw session is active
• continue to restrict /btw-merge and /btw-end to the active temp session where they actually work

0.3.5

• refine the published package metadata description to better describe the Claude Code-inspired btw workflow
• include the plugin version in /btw-status output so loaded builds are easier to identify in TUI

0.3.4

• refine the published package metadata description to better describe the Claude Code-inspired btw workflow

0.3.3

• rename the remaining /btw slash-command family members to hyphenated forms: /btw-merge and /btw-end
• keep command-family overrides consistent with the same hyphenated naming, such as /aside-merge and /aside-end

0.3.2

• rename the experimental server-side prompt command to /btw-prompt
• route /btw-prompt through the existing TUI-owned /btw open flow so the initial prompt runs inside the forked session
• namespace and scope prompt handoff files to the origin session to avoid cross-session collisions during local testing

0.3.1

• scope /btw command visibility to the current session so unrelated sessions do not incorrectly show /btw-end
• handle /btw-status directly in the TUI with a toast instead of sending it through the agent loop

0.3.0

• add direct non-LLM dispatch for /btw-prompt while keeping the proven TUI handoff flow
• remove temporary debug slash commands and trim unused server helpers
• improve experimental runtime logging for live debugging and restore the file-based prompt handoff after the parent-linked refactor failed in the live host

0.2.3

• add direct non-LLM dispatch for /btw-prompt while keeping the proven TUI handoff flow
• remove temporary debug slash commands and trim unused server helpers
• improve experimental runtime logging for live debugging and restore the file-based prompt handoff after the parent-linked refactor failed in the live host

0.2.2

• restore /btw to TUI-only ownership and move the seeded server-side entrypoint to /btw-prompt

0.2.1

• publish the side-session-only release from the OIDC trusted publishing workflow

0.2.0

• remove /btw_popup and its popup-dialog runtime so the plugin focuses on temporary side sessions
• load active bytheway sessions cleanly, keep the sidebar indicator aligned with the active temp session, and improve command-family overrides for local installs

0.1.5

• align the runtime plugin id with the published package name and add direct server-entry coverage
• harden popup and temp-session cleanup for canceled runs and failed /btw-end deletes
• add an optional OPENCODE_BYTHEWAY_COMMAND env var to rename the /btw slash-command family
• pin Bun in CI and release workflows and document local file:// plugin development setup

0.1.4

• publish a clean release from the planner-aligned workflow after the earlier workflow-only tags failed before matching package metadata

0.1.2

• align the standalone release workflow more closely with opencode-planner before the next publish attempt

0.1.1

• rename the npm package to opencode-bytheway so the standalone repo can publish under a clean available name

0.1.0

• add /btw for same-terminal temporary side sessions
• add /btw-end to return to the original session and close the temp session
• add /btw_popup for one-off popup questions that preserve the current screen
• improve popup rendering, copy feedback, and streaming stability
• publish from the standalone opencode-btw repository using a root package and root release workflow

Release

• CI and release publish from repo root.
• The release workflow does not bump package.json; bump the version and commit it before tagging.
• Stable release tags only. Tag format is v*, and the tag version must match package.json exactly.
• The workflow runs bun run test, bun run build, publishes to npm, and creates the GitHub release.

Before tagging:

bun run build
bun run test
bun run test:integration
npm pack --dry-run

Release checklist:

# update package.json version, for example x.y.z
# update CHANGELOG.md, including the OpenCode version the plugin was built against
# update the README.md changelog section with the same release details for npmjs.com
git add package.json CHANGELOG.md README.md
git commit -m "chore: release x.y.z"
git tag vx.y.z
git push origin main
git push origin vx.y.z

After install, verify the TUI plugin commands load:

• /btw, /btw-merge, /btw-end, /btw-status, /btw-prompt