[FEATURE]: Add session picker entry point at startup (e.g. -r, --resume or -s without value)

[hiyochi]

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

When launching opencode (TUI) at a project, it is easy to forget the exact ses_... id of a previous session. Today the only ways to resume one are:

• Run opencode first, then use the in-TUI /sessions picker
• Pass the opaque ses_... id explicitly via -s / --session

I would like a startup-time entry point that opens the session picker, the same way Claude Code does with claude --resume ("Opens the session picker" per the Claude Code CLI help text). This drops the user straight into the existing session picker for the current project, so they can resume a conversation without first entering an unrelated TUI session.

Proposed shape

I am flexible on the exact flag layout and would like the maintainers' input during the design review. Two reasonable options, both scoped to the current project / working directory:

• Option A: new -r, --resume flag (Claude Code parity)
  • opencode --resume -> open session picker for the current project, then load the chosen session into the TUI
  • -s / --session semantics are unchanged: it still requires a ses_... id and continues the given session (or errors)
• Option B: extend -s, --session to accept no value
  • opencode -s / opencode --session (no value) -> open session picker
  • opencode -s ses_xxx (with value) -> current behavior
  • Optional: also add --resume as an alias for the no-value form

I'd prefer Option A for two reasons:

1. It mirrors Claude Code and keeps -s / --session semantically simple ("give me a session id, I will continue it").
2. --resume is discoverable on its own in opencode --help, while "no-value -s" is more of a quirky shorthand.

Inverting the flag to an explicit --resume also keeps the "give an id" path loud and explicit, which is preferable to silent fallback.

Scope

• Picker contents: only sessions belonging to the current project / working directory, matching the existing TUI /sessions behavior. Cross-project listing is being discussed in [FEATURE]: Cross-project session list / picker for TUI #31932; this proposal intentionally does not overlap with it.
• Filter / search: reuse the existing TUI /sessions dialog (or the same underlying GET /session?directory=&search= query) instead of introducing a new picker
• Fork support: --resume --fork should fork the resumed session, mirroring the existing --session --fork behavior.
• --continue interaction: --resume and -c / --continue should be mutually exclusive, or --continue should take precedence (same as the current -c overrides -s behavior discussed in Correct CLI --continue --session syntax for persisting sessions is malfunctioning. #11680). Open to maintainer preference.
• Headless / non-interactive: out of scope for this proposal. The headless path already has a clean way to continue a known session via opencode run -s ses_xxx "...", and combining --resume with opencode run would force an interactive picker into a non-interactive command.
• V1 / V2 alignment: opencode is currently building out a V2 session core (see [FEATURE]: Cross-project session list / picker for TUI #31932's 2.0 label). I'm not sure whether this flag should land in the V1 CLI surface or be implemented against the V2 core. Open to maintainer guidance on which branch / layer this should target.

Non-interactive behavior

--resume requires an interactive picker and therefore a TTY. In non-TTY contexts (pipes, CI, nohup, tmux send-keys from a non-tty parent) it should fail fast with a clear error pointing the user at -s <session_id>, not silently fall back to a default. Open to maintainer preference on the exact error wording.

Why this is small

• CLI flag wiring: add --resume to the yargs builder in packages/opencode/src/cli/cmd/tui.ts (the same place -s is declared). No changes are needed in run.ts because opencode run --resume is intentionally unsupported.
• Resolution: when args.resume is set, call the existing SessionV2.list({ directory }) (or current equivalent), open the same dialog used by TUI /sessions, and feed the chosen SessionID into the existing -s resolution path.
• No backend / DB schema changes required.

Picker implementation

The picker should reuse the existing TUI /sessions dialog rather than introducing a separate UI:

• Single source of truth for filtering, sorting, keybindings, and rendering
• Inherits the fixes being discussed in TUI /sessions picker only shows recent sessions #13877 (recent-sessions cutoff) and in [FEATURE]: Cross-project session list / picker for TUI #31932 (cross-project view) automatically once those land
• Visual style and ordering match /sessions 1:1

Use case

# In a project directory, resume a previous conversation interactively
opencode --resume

# Once the picker is dismissed, the chosen session is loaded into the TUI
# exactly as if the user had selected it from the in-app /sessions dialog.

# In a script / CI, you already know the id (e.g. captured from a prior run
# via `opencode export`); the existing `-s` / `--session` flag continues to
# work and is the recommended path for non-interactive pipelines.
opencode run -s ses_abc123 "follow up after CI run"

Willing to implement

I am happy to send a PR for this. Before doing so I would like to confirm with the maintainers:

1. Option A vs Option B (or both) above
2. Whether the picker should be reused from the TUI /sessions dialog, or a separate lighter-weight picker
3. Whether --resume should be its own top-level flag, or added as an alias on --session
4. The exact error wording for the non-TTY case
5. Whether this should land on the V1 CLI or against the V2 session core

Happy to align with anyone who is already working on this area (#31932) before opening the PR.

Related issues

• [FEATURE]: Cross-project session list / picker for TUI #31932 — [FEATURE]: Cross-project session list / picker for TUI (in progress; this proposal intentionally scopes to the current project to avoid overlap)
• TUI /sessions picker only shows recent sessions #13877 — TUI /sessions picker only shows recent sessions (the data source for the proposed picker; worth aligning with)
• Correct CLI --continue --session syntax for persisting sessions is malfunctioning. #11680 — -c vs -s precedence (precedent for how --resume should interact with --continue)

[OpeOginni]

@hiyochi have you seen the --continue or -c command?

[hiyochi]

@OpeOginni thanks — yes, I'm using -c already for "just keep going". My problem is the middle case between -c and -s ses_xxx:

• -c always picks the most recent session in the current project. That's fine if my last session is the one I want, but I often have 2-3 in-flight ones (e.g. a refactor, a bug fix, and a doc pass) and the "most recent" is not the one I want to resume right now.
• -s ses_xxx requires me to know the opaque id, which I usually don't have without first opening the TUI and running /sessions — which defeats the "I'm starting a fresh terminal to resume" workflow.

--resume is the missing "let me pick one from the list" step in between.

claude --resume works the same way: it's not a replacement for -c (which keeps its "most recent" semantics in Claude Code too), it's a separate "interactive picker" entry point.

[OpeOginni]

@hiyochi I understand now, Idk if its a feature the team wants to ship, but lets just see and hope