Oko
Oko/Docs

Command reference

oko sessions adopt

Resumes an external session of a harness the catalogue gives a resume command (Claude Code, Codex, Jeden) inside a broker session, its model traffic routed through Brama.

Invocation#

Command
oko sessions adopt TARGET [--text TEXT] [--no-submit] [--socket PATH]

Inputs and options#

  • TARGET is a pid, a session id, latest, latest_codex, latest_claude, or words of the process's directory or command line; `oko sessions list --external` shows the candidates. A process's session is read from its command line, or from the live transcript it holds open for writing as Transcript Lake's sources declare it: a file named after the session (Claude Code, Codex) or a file in a directory named after it (Jeden's .jeden/sessions/<id>/transcript.jsonl). A process that holds no such transcript yet — a Jeden that has not opened a session — is not a candidate.
  • A Jeden is resumed as `jeden --resume-session <id>`, which loads the session's turns into a new Jeden session. Jeden speaks Brama's own contract, so it is not given a proxy overlay: it is continued as a task of the transcript it holds open, on a subscription lease handed to it in JEDEN_LEASE, exactly as `oko sessions resume` starts it. Claude Code and Codex are pointed at the proxy through their catalogue overlay.
  • --text types text once the resumed harness has printed; --no-submit omits the carriage return.

Output and state effect#

  • Starts a resumed broker session, optionally types the text, and prints an adoption receipt: adopted, broker_session, ready_before_send, sent_text and submitted.
  • Oko Desktop's Sessions screen shows the same candidates under Outside the broker (each process, its session, directory and command line) and adopts one with Adopt and an optional text, answering with the broker terminal or the refusal word for word; it reads them through the native API's sessions domain (external; adopt with target, text and submit).

Refusals and safe exits#

  • A missing TARGET refuses with “oko sessions adopt requires <id>” and an empty --text with “oko sessions adopt --text takes the text to type; leave it out to type nothing” (exit 2); through the native API an empty text refuses with “sessions adopt takes the text to type; leave text out to type nothing”. “no resumable external terminal processes”, “no external terminal matched <target>”, “the harness catalogue declares no resume command for <harness>”, “<harness> session <id> (pid <pid>) holds no transcript open, so it cannot be continued on a lease”, a lease Brama refuses (“…; jeden reaches its models only through Brama, so it is not started”), a missing router identity and broker or send failures exit unsuccessfully.

CLI reference#