Oko
Oko/Docs

Command reference

oko sessions list

Every terminal session Oko's broker holds, with whether its process still runs, the publication it backs and the command that attaches to it (`oko sessions attach 'ID' --socket 'BROKER'`); with --external, the agent processes running on this machine that the broker did not start.

Invocation#

Command
oko sessions list [--external] [--socket PATH] [--json]

Inputs and options#

  • --socket selects the broker's control socket; the default is the installed one (~/.oko/oko-pty-broker-<user>.sock, where <user> is the login name the account database gives this process's uid — the same for a launchd job or `env -i` that sets no USER — or OKO_BROKER_SOCKET). Oko Desktop names the same socket the same way.
  • --external lists the resumable Claude Code, Codex and Jeden processes found through ps and lsof instead, each as {pid, kind, display_name, cwd, session_id, command}; it does not adopt them. The real journey `JEDEN_BIN=… cargo test --test agent-external -- --ignored` starts `jeden rpc` in an isolated home and requires it to be listed with its session id only once it has opened a session.

Output and state effect#

  • Prints {sessions: [{broker, isAlive, published, attachCommand}], orphanedPublications, registryFailure, retiringBrokers}: each broker session beside this member's shared-session row, and the member's still-active publications no local session backs. Nothing is changed. Oko Desktop's Sessions screen shows the same list through the native API's sessions domain.
  • After an install replaced the running service, the replaced build keeps only the terminals it started and answers for them on <socket>.retired.<pid> while the installed build serves new terminals on the control socket at once. Those terminals are listed on the one socket with broker.heldBy {socket, retiring: true}, and retiringBrokers names each retired socket with the terminal ids it still holds; a retired broker ends with its last terminal. send, screen, resize, repaint and end for such a terminal go through the control socket and are answered by the broker holding it.

Refusals and safe exits#

  • A broker that does not answer refuses with “Oko's PTY broker at <socket> is not answering: <error>; it runs inside the Oko service (`oko serve`)”. A registry that cannot be read is not a refusal: the list is printed with registryFailure naming why.
  • A broker row the list cannot account for refuses the list naming the row, never listed as a live, attachable session: “Oko's PTY broker listed a session without <id | processIdentifier | executable | createdAt>: <row>”, “… listed process <n>, not a process id: <cause>: <row>” and “… listed process <n>, which names a process group: <row>” (the kernel reads a pid of 0 or below as a process group, which always exists).
  • With --external, a process listing that cannot be read refuses with “/bin/ps -A -o pid=,command= did not run: <cause>” or “… failed (<status>): <stderr>” rather than answering no processes; the same refusal reaches `oko sessions adopt` and the native API's sessions.external. A process whose open files lsof cannot read is left out and named on stderr (“# the open files of pid <n> are not read: <cause>”).

CLI reference#