Status: Current
OpenCode 2 uses a shared service/data store. Sessions belong to locations and
carry location.directory; a server URL does not identify a project.
The tools therefore use these identities:
- Project: canonical directory.
- Prompt target: OpenCode session ID in that directory.
- Display: an optional, explicitly registered tmux pane.
The OpenCode server is user-managed. agentp and ocmux health-check it but do
not start or stop it.
The nearest .ocmux.json, found by walking upward from the working directory,
is the durable source of truth:
{
"version": 2,
"directory": "/home/user/project",
"session": "ses_abc",
"server": "http://localhost:4096",
"annotations": {},
"broadcast": ["ses_abc", "ses_def"]
}directory, session, and server route prompts. annotations stores optional
per-session reminders. broadcast exists only with at least two selected main
sessions and is removed as soon as broadcast mode ends (Enter/ESC/q) or any
session is picked in the normal switcher. On open it is validated against the
live session list: a valid list starts the picker directly in broadcast mode,
while a stale/invalid one is cleared and the normal state shown. Writes use a
temporary file plus atomic rename.
No tmux socket, pane ID, process ID, or TUI assignment belongs in project state. Those values are ephemeral and machine-local.
ocmux tui registers its current $TMUX_PANE. The registry lives at:
$OCMUX_RUNTIME_DIR/ocmux-tuis.json (test/override)
$XDG_RUNTIME_DIR/agentp/ocmux-tuis.json (normal)
/tmp/agentp-<uid>/ocmux-tuis.json (fallback)
The directory is mode 0700 and registry files are mode 0600 where the
platform permits it. Updates are lock-protected and atomically renamed.
Each instance records:
- opaque instance ID;
- random verification token;
- tmux socket and pane ID;
- dedicated/shared mode;
- last directory, server, and session;
- the directory and session currently displayed (so routing can skip a respawn that would change nothing);
- foreground wrapper PID and current child PID (diagnostic only);
- registration/update timestamps.
The pane itself receives @ocmux_tui_id and @ocmux_tui_token tmux options.
Before a destructive pane operation, both must match the protected registry.
This prevents a stale registration from respawning an unrelated pane. Pane IDs
remain useful after move-window, join-pane, or break-pane within the same
tmux server; recording the socket disambiguates multiple tmux servers.
There are two assignment slots:
- one dedicated TUI per canonical project directory;
- exactly one shared TUI across all projects and server URLs.
There is no --global alias.
When ocmux selects or inspects a session — or agentp sends a prompt or
re-submits a deferred ticket (section 8) — the display is resolved in order:
- live TUI dedicated to the target directory;
- the one live shared TUI;
- no display (headless success).
A stale/dead dedicated registration is ignored, so routing falls back to the shared registration. A stale shared registration yields headless operation. Display failure is a warning and never rolls back the durable session choice.
The shared TUI is deliberately not server-scoped. When a selected project uses a different server, the same pane reconnects to that server.
ocmux tui [--shared] [directory]:
-
Requires
$TMUXand$TMUX_PANE. -
Resolves
.ocmux.json, server, directory, and session. A shared TUI may run without a state file, in which case it uses the current directory and the default server ($OCMUX_SERVERorhttp://localhost:4096). -
Health-checks the server and validates the session, creating one with a model when necessary.
-
Marks and registers the current pane.
-
Stops the displaced wrapper for the same dedicated/shared slot, preserving its pane.
-
Spawns
opencodeas a foreground child with inherited stdio:opencode --server <url> --session <id> <directory> -
Forwards
SIGHUP,SIGTERM, andSIGINTto the child. -
On child exit, unregisters only when instance ID and token still match.
Token-conditional cleanup prevents an old wrapper from deleting a replacement's new registration.
OpenCode exposes no HTTP operation for steering one specific TUI client. A registered pane is therefore switched with:
tmux -S <socket> respawn-pane -k -t <pane> -c <directory> \
"<ocmux> tui [--shared] --server <url> --session-id <id> -- <directory>"
The new ocmux tui process re-registers the pane and hosts the new OpenCode
child. Server-side session execution continues while the old client disconnects.
Client-local state—draft prompt, scroll position, dialogs, and tabs—is lost.
Routing is idempotent: the registry records the directory and session the pane currently displays, so a switch to the same project/session is skipped without respawning.
Native TUI navigation is temporary inspection and is not observable through the OpenCode HTTP API. The next ocmux selection restores the canonical target.
Initializes .ocmux.json, selecting the newest main session in the directory
or creating one with a model. It creates no tmux session, window, or pane.
--force --server <url> repoints existing state and refreshes the routed TUI.
Registers and hosts a dedicated or shared TUI as described above. --shared
is valid only for this command. --server overrides the project's recorded
server for the launched wrapper; when --shared runs without a state file it
falls back to the default server. Management modes are:
ocmux tui --list— prune stale entries and print every live registration;ocmux tui [dir] --status— inspect the dedicated slot for that project;ocmux tui --shared --status— inspect the shared slot;ocmux tui [dir] --detach— unregister the dedicated slot;ocmux tui --shared --detach— unregister the shared slot.
--detach clears the pane's verification options but does not stop OpenCode or
destroy the pane. Management modes do not require running inside tmux.
Opens the current project's session picker. Picking writes that project's
session and refreshes its routed TUI. Merely opening the picker also routes the
applicable TUI to the project's stored session (skipped when it already shows
it), so starting ocmux in a project switches the display even without picking
a row. When the recorded server is unreachable but the default server answers,
ocmux offers on a TTY to repoint the project to the default and rewrites
server. Session creation, rename/delete,
annotations, agent/model choice, broadcast selection, search, and project
inspection operate through OpenCode's API. Deleting the session currently
selected adopts the session under the cursor as the new current (state write,
TUI refresh, and list highlight); deleting any other session leaves the current
selection unchanged. In broadcast mode d deletes just the cursor session
while D (Shift+d) deletes every selected session at once — after confirming,
broadcast mode ends and the row under the cursor becomes the new current.
In broadcast mode Enter switches to the cursor session and ends broadcast,
while ESC/q cancel it; every exit clears the persisted broadcast list, as
does picking any session in the normal switcher, so a stale selection never
survives to keep agentp broadcasting. On start the picker adopts a stored
broadcast only when at least two of its ids still name listed sessions; it then
opens in broadcast mode (re-anchoring on a selected session when the stored
session is not in the list), and otherwise clears the invalid list before
showing the normal state.
Interactive prompts (create/rename/reminder/delete/delete-all) take over the
status bar and flip its background from brown to light yellow — the same color
as the session-list pointer — so an active question is immediately visible.
The broadcast info line (Broadcast to sessions: …) never wraps: it holds up
to 480 characters of names (or the terminal width, whichever is smaller), and
an oversized selection is truncated from the beginning with a leading ....
Live activity. Every listed session that is currently running (a foreground
drain, per GET /api/session/active) shows an animated spinner in its row, and
the info panel's status says BUSY. The picker's initial runningIds is a
snapshot taken at open; while the picker stays open it re-polls that endpoint
every second and updates the set, so sessions that start a turn after the menu
opened begin spinning and sessions that finish stop — the animation timer starts
and stops to match. Failures of the poll degrade silently: the previous set
stays and the next poll retries.
Pending-answer awareness. While the picker is open it re-polls the project
every 2 seconds (GET /api/form and GET /api/permission/request, both
location-scoped with the location[directory]=… deepObject parameter) and
tracks which session ids currently await an agent question (a form) or a
permission reply. Sessions carry two independent marker columns — ❓ (question)
and 🔒 (permission) — each a fixed 2-column cell whose placeholder keeps rows
aligned when a session has no marker. A single 🔔 leads the status bar (forced
left-aligned) whenever any listed session is waiting, and the cursor session's
marker columns are pinned to the info panel's top-right corner (the Title line
is padded out to cols - cells.length).
Failures of the poll degrade silently: the previous sets stay and the next poll
retries.
Answer mode (A). When the cursor session has a pending form, A fetches
GET /api/session/{id}/form and switches to a dedicated answer screen. It
renders each visible field as a header plus its option rows; multi-select
fields toggle extra entries, boolean fields render Yes/No, choice fields with
custom get a "Type your own answer" row, and option-less (free-text/numeric)
fields open the status-bar input directly. Fields with hidden or when
conditions are filtered live over the answers chosen so far (a gated group
appears the moment its gate question is answered). The final Submit answers (n/m answered) row posts the keyed answer map
(POST /api/session/{id}/form/{formID}/reply, {answer: {fieldKey: value}}).
On success the remaining forms are re-fetched: the next pending form is
answered in turn, or the picker returns to the session list with a
✔ Answers submitted. notice. A 400 rejection shows the server's message
(message or error.message from the body) in the status bar and stays in
answer mode for correction; a 409 (already settled elsewhere) reports the
server message and returns to the list. h toggles the answer-mode help,
q/ESC cancels without answering, Ctrl+C exits.
Permission answering (P). Permissions are answered from a dedicated
screen opened with P on a session with a pending permission request (🔒
marker). It re-reads the location-scoped GET /api/permission/request list
(currently answered requests settle out of it) and filters to the cursor
session. Each request is shown with its action, resources and optional message;
one key answers it — o/1 allow once, a allow always, r reject — posting
POST /api/session/{sessionID}/permission/{requestID}/reply with
{decision: 'once' | 'always' | 'reject'}. Success drops the request and
advances to the next; after the last it returns to the session list with a
✔ Permission answered. notice. A rejected reply (400) shows the server's
message in the status bar and stays; h toggles a help screen, q/ESC leaves
everything pending, Ctrl+C exits.
Non-interactively writes the selected session and refreshes its routed TUI.
Configured projects are discovered from /api/project plus session locations;
only directories containing .ocmux.json are included. This captures worktrees
that are locations but not separate OpenCode project records.
By default the switcher only inspects sessions through the routed TUI and never
writes another project's state. --all-projects lets the outer session picker
move to another project and subsequently update that project's state.
The switcher shows the same pending-answer awareness as the session picker: session rows carry their own ❓/🔒 marker columns, and a folded project row shows them aggregated over all of its sessions' pending forms/permissions (fetched once per project when the switcher opens, from each project's recorded server).
Lists configured projects, selected sessions, and display status:
project— a live dedicated TUI wins;shared— the live shared fallback applies;headless— no live registration.
-l also prints the server URL.
The old managed-window kill and resurrect commands do not exist.
agentp resolves project/session/server from explicit options and the nearest
state file, then sends directly to the session API. Sending a prompt (normal or
--defer) also routes the project's TUI to the target session, so the answer
streams in view: the pane is respawned only when it does not already show that
project/session. Re-submitting a deferred ticket does the same for the ticket's
session, whose project directory is derived from the session's own location.
Routing is best-effort and never fails the prompt. It resolves like section 4
(dedicated → shared → headless, silent when no pane is registered), is skipped
for broadcast prompts (no single session to show) and for the detached
--defer-child worker, and routing always keys on sessionId/sessionIds —
the human-readable session name on a ticket is display-only.
- Missing/unreachable server: command fails before registration or switching.
- Missing TUI: session selection succeeds headlessly.
- Dead pane or mismatched token: registration is pruned and fallback routing is attempted on the next resolution.
- Failed
respawn-pane: selected state remains valid and a warning is printed. - Manual OpenCode exit: foreground wrapper removes its own registration.
- Replaced wrapper exits late: token check prevents it removing the new owner.
- tmux restart/reboot: pane checks invalidate and prune old runtime entries.
- Multiple tmux servers: recorded
-S <socket>targets the correct one.
.ocmux.jsonnever identifies a process or pane to terminate.- Destructive pane operations require matching registry and pane tokens.
- Commands are built from validated server/session/directory values with shell quoting; no command string is read from project state.
- Runtime registry and lock files are private to the user.
- Wrapper/child PIDs are diagnostic only and are never used as durable identity or as the target of a destructive operation.