Skip to content

Resume OpenCode sessions on restore, alongside Claude Code and Codex #290

Closed

Description

@Mattheinrichs

What are you trying to do?

Run one opencode session per pane across a few workspaces, and have wmux reopen those same conversations after a restart, the way it already does for Claude Code and Codex.

What would you like wmux to do?

An opt-in Resume OpenCode sessions on restore switch (Settings → Workspace) that reopens each terminal that was running opencode with opencode -s <session id> in the directory it was in.

Sketch, in the shape of the existing two:

  • Report the handle. The wmux opencode plugin already receives the v2 session events, whose payloads carry sessionID (e.g. session.renamed → data.sessionID). It would call wmux report-session <id> --provider opencode. Today that is refused: reportAgentSession returns null for any provider other than claude/codex (agent-state.ts), and the CLI usage string says [--provider claude|codex].
  • Stamp it. A stampOpencodeSessionIds next to stampCodexSessionIds (codex-resume.ts, wired through agent-session-persistence.ts), writing opencodeSessionId on the persisted surface. Ids are ses_<base62>, so a validator like CODEX_SESSION_ID_RE applies.
  • Replay it. A branch in withClaudeResume (renderer/hooks/claude-resume-command.ts) appending opencode -s <id>, gated on the new pref, next to the existing claude --resume / codex resume branches.
  • Pruning. opencode -s <id> creates a session when the id no longer exists, so a stale handle resurrects an empty conversation. Claude prunes by transcript existence; Codex owns its history. For opencode the authority is whatever server the CLI is configured against: opencode session list --format json. Spawning the CLI on every start may be too slow, so pruning at all is your call; otherwise the recreate behaviour is the price.

No opencode-side change is needed: -s/--session (continue, or create if missing), session list --format json, and session ids on plugin events are all already there.

What do you do today instead?

Run opencode panes from a profile whose startup command is opencode -c. wmux re-runs a pane's startup commands on restore, so something comes back, but -c means "newest top-level session for this directory": it is not the tab's conversation, and two panes in one folder resume the same session.

Activity

  1. amirlehmam commented on Oct 15, 2026

    @amirlehmam
    Owner

    Thanks for the detailed sketch. It mapped onto the code almost exactly.

    Shipped in v2.25.0: Settings → Workspace → Resume OpenCode sessions on restore (off by default, like Claude and Codex).

    • Report: the wmux OpenCode plugin (now v7; wmux reinstalls it on the next launch) calls wmux report-session <id> --provider opencode, and agent-state.ts accepts the new provider. Ids must match ses_<base62> in the plugin, in main and again in the renderer before anything is typed. That check is strict on purpose: Claude's looser validator would accept an OpenCode id, so Claude stamping now skips any record that isn't Claude's.
    • Stamp: stampOpencodeSessionIds sits next to the Codex one, and the providers are mutually exclusive per tab.
    • Replay: opencode -s <id>, appended after the profile's own startup commands and gated on the new switch. A tab carrying two providers' handles types nothing.
    • Which session: the last top-level session anything happened in. A task subagent is its own session firing events on the same pane, so a session created with a parent is never reported. On v1 that's info.parentID on session.created/updated. On v2 it's the flat data.parentID. Watch out on v1: info.parentID on message.updated is a message id. I checked all of this against real opencode-ai 1.18.35 and @opencode/cli 2.0.24 runs that launch a subagent. In both, only the parent was reported.
    • Quitting OpenCode releases the handle (wmux release-agent --provider opencode --session <id>), so that tab comes back as a shell. wmux refuses the release while wmux itself is quitting, the same way it does for Codex.
    • Pruning: I skipped it, as you suggested it might be: a stale id costs a recreated empty session, and calling opencode session list on every start felt like the wrong trade.

    One limitation on OpenCode 2 that you'll probably run into: by default v2 runs a single opencode serve --service for every TUI on the machine, and plugins live inside it. That server's WMUX_SURFACE_ID is only the pane that happened to start it, so reporting from there would resume pane B's conversation in pane A. In that mode the plugin reports nothing. Start OpenCode 2 with --standalone (your profile's startup command can be opencode --standalone) and the session is saved per tab. A tab that already has a saved session is resumed either way. In v2's run mode the plugin also never sees a clean exit, so a deliberate quit there may not clear the handle. The details are in docs/opencode-plugin.md.

    If you know of a way for a v2 server plugin to tell which TUI client drove an event, I'd like to hear it. That's what it would take to lift the --standalone requirement.

  2. Mattheinrichs commented on Oct 15, 2026

    @Mattheinrichs
    ContributorAuthor

    Thank you and a quick follow-up. Yes - I am very much in the server place. My TUI is a client of a remote server, so the plugin lives in the server process, never sees WMUX_SURFACE_ID, and nothing is reported.

    The CLI (TUI) plugin is the documented way out. The v2 CLI plugin guide says a CLI-side plugin configured in cli.json "remains active against remote servers", and its context has everything needed to report the pane's session without any server attribution: ui.router.current() gives the session being viewed, ui.tabs.list() the open tabs with active/busy/attention, data.on/data.listen the event stream, client works against a remote server, and setup returns a cleanup, which is where release-agent on quit goes. So the server-side half and a CLI half are not alternatives: the CLI half covers remote and shared-server setups, and it can carry blocked/activity reporting too, not just the session handle.

    Packaging-wise this looks small: a package that exports both . and ./tui loads both halves, and a CLI-only package can be listed in cli.json. wmux currently writes a single local file to ~/.config/opencode/plugin/wmux.js, so the CLI half would need to be reachable as a package/entry the TUI loads, plus whatever registering it in cli.json requires.

    One secondary thought, not a request: opencode's OSC 7501 program-status records carry {state, id: sessionID, title} into the pane's terminal and would be the agent-agnostic version of this for setups with no plugin at all, but today idle sessions emit no id-bearing record and the emission is gated by an undocumented setProgramStatus() handshake. The CLI half is the smaller fix.

    Happy to test a build against my setup (Windows wmux, opencode v2 client against a remote server) if it helps.

  3. Mattheinrichs commented on Oct 16, 2026

    @Mattheinrichs
    ContributorAuthor

    Posting here rather than reopening — if this should live in a fresh issue so it stays in your triage view, say so and I will open one and link it.

    Answering the open question from the shipped-side: the server half does not need to attribute events to a TUI client, because the client can report for itself.

    ui.router.current() is the route store: packages/tui/src/context/route.tsx is createStore<Route>(…) exposed as get data(), and packages/tui/src/plugin/api.tsx:226 is current() { return host.route.data } — the same store the host memoizes on. packages/tui/src/plugin/runtime-plugin-support.bun.ts maps @opencode/plugin/tui and solid into the host runtime, so a non-JSX CLI plugin can own the computation itself with createRoot + createEffect and dispose it from setup's cleanup. No polling, no lag. One docs nit: router.current() lacks the "reactive when read in a Solid computation" note that tabs.list(), model.current() and panel.current() carry.

    Prototype:

    // wmux CLI-side (TUI) half — reports the pane's viewed OpenCode session to
    // wmux, so "Resume OpenCode sessions on restore" works when the TUI is a
    // client of a remote or shared OpenCode server.
    //
    // Install: <config>/plugins/wmux-cli/tui.js
    // Fallback: cli.json -> {"plugins": ["<absolute dir>"]}
    import { Plugin } from "@opencode/plugin/tui"
    import { execFile } from "node:child_process"
    import { createEffect, createRoot } from "solid-js"
    
    const ID_RE = /^ses_[A-Za-z0-9]{8,64}$/
    
    function callWmux(argv) {
      const cli = process.env.WMUX_CLI
      const node = process.env.WMUX_NODE
      const surface = process.env.WMUX_SURFACE_ID
      if (!cli || !surface) return
      // WMUX_NODE is absent in WSL by design (a Windows path), so fall back to a
      // JS runtime on the pane's PATH the way the shipped plugin does.
      const opts = { windowsHide: true }
      if (process.env.WMUX_NODE_ELECTRON === "1") opts.env = { ...process.env, ELECTRON_RUN_AS_NODE: "1" }
      execFile(node || "node", [cli, ...argv, "--surface", surface], opts, () => {})
    }
    
    export default Plugin.define({
      id: "wmux.cli",
      setup(ctx) {
        let last
        const dispose = createRoot((dispose) => {
          createEffect(() => {
            try {
              const route = ctx.ui.router.current()
              if (!route || route.type !== "session") return
              // A viewed subagent is not a resumable handle: report its root,
              // mirroring the server half's parentID skip.
              const sid = route.sessionID
              const root = ctx.data.session.root(sid)
              const id = root && root !== sid ? root : sid
              if (id === last || !ID_RE.test(id)) return
              last = id
              callWmux(["report-session", id, "--provider", "opencode"])
            } catch {}
          })
          return dispose
        })
        return () => {
          dispose()
          if (last) callWmux(["release-agent", "--provider", "opencode", "--session", last])
        }
      },
    })

    Install is <config>/plugins/wmux-cli/tui.js — a directory under plugins/ resolves <dir>/tui through Host.resolve → Bun.resolveSync, no package.json needed — or cli.json → {"plugins": ["<absolute dir>"]}.

    Verified on Windows wmux + a WSL pane with the TUI as a client of a remote OpenCode server (so the shipped server-side half never runs):

    • the plugin loads once per TUI process; WMUX=1, WMUX_CLI set, WMUX_NODE unset (by design in WSL), runtime falls back to node on PATH
    • route type=session fires with the real ses_… on navigation, and re-fires dedupe
    • wmux report-session <id> --provider opencode over the npiperelay transport answers {"accepted": true}
    • wmux agent-state then lists those surfaces with their session ids

    Not yet re-tested for this shape: the restore itself (opencode -s <id>), which rides the path you already shipped for --standalone.

    Phase 2, same half: for panes whose server-side half can never run, this can also carry report-agent state — ui.tabs.list() (busy, attention), data.session.status(id), data.session.permission.list(id) / form.list(id) → --run-start / --run-end / --blocked. Today such panes read state: unknown with nothing blocked, which is what agent-state shows.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions