feat(opencode): fork the current session into a new tmux pane via keybind

[itse4elhaam]

Summary

Add a single-key workflow that opens a fork of the currently active OpenCode session in a new tmux pane.

The resulting pane must inherit the current working directory and load the exact current OpenCode session as a fork, allowing both sessions to continue independently side by side.

Desired UX

While focused inside an active OpenCode TUI session running in tmux:

1. Press one configured keybind.
2. A new tmux pane opens, preferably to the right of the current pane.
3. The new pane starts OpenCode in the same working directory.
4. OpenCode forks the exact session that was active when the keybind was pressed.
5. The original pane and session remain untouched.

The user must not need to:

• manually copy a session ID
• open the session picker
• type a shell command into the OpenCode prompt
• infer the current session from timestamps, titles, or working-directory heuristics

Repository context

Relevant existing files and conventions:

• .tmux.conf
  • tmux prefix is C-a
  • directional pane splits already preserve #{pane_current_path}
  • tmux configuration is currently kept in this root file
• .config/opencode/opencode.json
  • contains the active OpenCode plugin configuration
• .config/opencode/
  • appropriate location for an OpenCode plugin or TUI configuration, if required
• scripts/
  • appropriate location for a reusable executable helper, if required
• .config/opencode/context/domain/dotfiles-architecture.md
  • repository uses GNU Stow
  • scripts should be idempotent and pass ShellCheck
  • commits should use Conventional Commits

Do not edit backup files such as *.bak unless there is a specific documented reason.

Investigation required

Before implementing, verify the capabilities of the currently installed/supported OpenCode version rather than relying on stale examples.

Determine:

1. Whether OpenCode keybindings can invoke a custom command or plugin action.
2. Whether an OpenCode plugin hook, custom command, environment variable, API, or CLI command can reliably expose the exact active session ID.
3. The current supported CLI syntax for opening a session and forking it.
4. Whether OpenCode already ships a native action or command that can be composed with tmux.
5. Whether Oh My OpenAgent or another already-installed plugin provides this behavior.

Prefer documented, stable APIs. Do not query OpenCode's internal database using directory/time heuristics unless no supported mechanism exists, and do not use such a heuristic silently.

Preferred implementation shape

Choose the smallest reliable design after completing the investigation.

A likely shape is:

OpenCode keybind or tmux keybind
        ↓
OpenCode-aware command/plugin obtains exact active session ID
        ↓
small helper invokes tmux split-window
        ↓
new pane runs OpenCode with the session ID and fork option

Possible components may include:

• a custom OpenCode plugin/action under .config/opencode/
• a custom OpenCode command under .config/opencode/command/
• a helper script under scripts/
• a tmux binding in .tmux.conf
• a TUI keybinding config file if supported by the installed OpenCode version

These are implementation options, not mandatory files. Avoid unnecessary layers.

Functional requirements

Session correctness

• The newly opened OpenCode instance must fork the exact active session.
• It must not pick merely the newest session in the same directory.
• It must not attach to and mutate the same session concurrently.
• The original session must remain active and unchanged.

tmux behavior

• Open the fork in a new tmux pane.
• Default placement should be a horizontal split opening to the right, unless existing conventions make another placement more appropriate.
• Start the new pane in the current pane's working directory.
• Preserve paths containing spaces or shell metacharacters.
• Do not interpolate the session ID or working directory unsafely.
• Do not use tmux kill-server or alter unrelated tmux state.

Keybinding

• Provide a single ergonomic keybind while OpenCode is focused.
• Prefer an OpenCode-native keybind if custom actions are supported cleanly.
• Otherwise, use a tmux keybind that behaves reliably without typing text into the OpenCode prompt.
• Check for conflicts with existing tmux and OpenCode bindings before choosing the final key.
• Document the chosen key and how to change it.

Failure handling

Provide clear, non-destructive errors for at least:

• command invoked outside tmux
• no active OpenCode session ID available
• opencode missing from PATH
• tmux pane creation failure
• unsupported OpenCode version/API

The current OpenCode session must continue normally if pane creation fails.

Maintainability

• Keep the helper focused and readable.
• Use set -euo pipefail for Bash unless another shell or language is better justified.
• Pass ShellCheck for shell files.
• Avoid hard-coded absolute home-directory paths.
• Follow the repository's GNU Stow layout.
• Do not introduce a dependency unless the benefit is substantial and documented.

Acceptance criteria

• From an active OpenCode session inside tmux, one keybind opens a new pane.
• The new pane starts in the same working directory as the originating pane.
• The new OpenCode process contains a fork of the exact originating session.
• Messages entered in the fork do not modify or redirect the original session.
• The workflow works when multiple OpenCode sessions exist in the same repository.
• Paths and arguments are safely quoted.
• Invoking the workflow outside tmux fails clearly and safely.
• Missing/unsupported session context fails clearly without opening an unrelated session.
• Existing pane navigation and split bindings continue to work.
• Any added shell script passes ShellCheck.
• Configuration and usage are documented in an appropriate README/context file or adjacent comments.

Manual test plan

1. Start tmux and open a repository whose path contains no spaces.
2. Start OpenCode and create enough conversation history to identify the session.
3. Trigger the new keybind.
4. Confirm a new pane opens on the expected side.
5. Confirm the new pane starts in the same repository.
6. Confirm the fork contains the original session history.
7. Send a distinct message in the fork and verify the original session does not change.
8. Repeat with two active OpenCode sessions in the same working directory and confirm the correct source session is forked.
9. Repeat in a directory whose path contains spaces.
10. Invoke the helper outside tmux and verify the error is clear.
11. Temporarily simulate a missing session ID and verify no unrelated OpenCode session is opened.
12. Reload .tmux.conf and confirm existing keybindings still work.

Deliverables

• implementation in the appropriate dotfiles paths
• any required OpenCode/tmux configuration
• concise documentation of:
  • chosen keybind
  • implementation approach
  • how the active session ID is obtained
  • how to change pane direction or keybind
  • known OpenCode version requirements
• verification notes or screenshots showing the original session and its independent fork side by side

Non-goals

• building a general tmux session manager
• changing the normal OpenCode session_fork behavior globally
• automatically creating git branches or worktrees
• forking background subagents
• restoring sessions after reboot
• adding broad tmux layout management

Implementation note

If OpenCode cannot expose the current session ID to an external command through a supported API, stop and document the limitation in the PR before introducing database inspection or heuristic session selection. A reliable partial solution is preferable to a shortcut that occasionally forks the wrong session.