Ocean Code Companion

The companion puts every Ocean Code session on your Macs on one board on your iPhone. A question or a permission that waits for you can be answered there, and the phone pushes when one waits. You can also send a session its next prompt, or stop a running turn. Each engine publishes its sessions to a relay (https://companion.plungeai.com, one inbox per Plunge account). The Ocean Code iPhone app reads that inbox. The Mac never accepts a connection: the engine dials out, and your answer comes back over the same socket.

Before you start

The companion uses your Ocean sign-in. Sign in once on each Mac:

oceancode login --provider ocean

Signing in alone sends nothing: an engine publishes only while at least one phone is paired with your account (see Privacy). Without a sign-in, every companion surface says so and does nothing else:

• oceancode companion … prints companion: not signed in — run `oceancode login --provider ocean` and exits 2.
• The pager's /companion shows Not signed in: run oceancode login --provider ocean.
• The engine logs companion: not signed in (oceancode login --provider ocean) once at start.

The companion is in the default build (the companion feature). A --no-default-features build leaves it out, and oceancode companion there prints companion is not in this build and exits 2.

Pairing a phone

Open the pairing code in either place:

• in the pager, type /companion. A window opens with the QR, the code, your account id and the phones already paired. Esc closes it.
• in a terminal, run oceancode companion pair. It prints the same QR with a caption line under it.

Scan the QR with the Ocean Code app, or type the code and the account id shown under it. The QR encodes oceancode://pair?u=<account>&c=<code>; the account id only routes the request, and the code is the secret. A code is 10 characters, works once, and expires after 10 minutes. Pairing gives the phone its own device token, which the phone keeps in its Keychain and the relay stores only as a hash. The phone never sees your Mac's sign-in.

What the phone shows

• The board. Your sessions, grouped by Mac, sessions that wait for you first, with the same codes, status words and plan progress as oceancode status (21 · oceancode status). A Mac that goes to sleep or quits Ocean Code turns offline within about a minute. Its sessions turn grey but stay on the board, and their open asks close as lost.
• A session. The title, the Mac, the folder, the plan row in progress and the next one, and its recent history: your prompts, the assistant's answers, the tools it ran (✓ or ✗) and its steps.
• An ask. A question shows its options, with multi-select and free text where the question allows them. A permission shows what is asked and a one-line summary (the bash command, or the file path), with the buttons Allow once, Always and Reject. A permission also shows how long it will wait.

Answering, prompting and stopping

An answer from the phone reaches the engine as if you had answered in the pager, and the session continues. The first answer wins, wherever it comes from. If you answer in the pager first, the phone's sheet closes, and a late tap reports that the ask is closed. If you answer on the phone first, the pager's card closes by itself.

When a session is idle, the phone can send it its next prompt, and the pager window shows the new turn. While a turn runs, Stop interrupts it, like Esc in the pager.

Push notifications

The phone gets a push for an ask that is still open 10 seconds after it opened. If you are at the Mac and answer within those 10 seconds, no push is sent. Asks that close at once, such as a permission a rule answered, never push either. There is no push while the app is open on the phone. In the app's settings, "Notify when done" adds a push when a session finishes, crashes or reports an error. When an ask closes, its notification is removed from the phone.

Permissions wait longer while a phone is paired

Without a phone, a permission request waits 30 minutes and is then rejected, so an unattended run never hangs. While at least one phone is paired, it waits 4 hours, because you are probably away and will answer when the push reaches you. The deadline the phone shows is the one in force when the request opened. See 12 · Permissions and sandbox.

Which sessions appear

Every engine that runs the companion is its own connection. Two pager windows, an Xcode session and a second Mac signed in to the same account all appear on one board.

Ocean Factory's desks set OC_COMPANION=0, so they never reach the board.

Xcode sessions show on the board, and their permission requests can be answered from the phone. Their questions cannot: in Xcode the question tool hands the question to the conversation and continues at once (20 · Permissions and questions), so nothing waits for an answer.

Settings

Both are also listed in 02 · Configuration.

Privacy

• Nothing is sent until a phone is paired. An engine that is signed in keeps its connection open only to learn when a phone pairs; until then it sends no session, no ask and no event.
• What the relay stores for a paired account:
  • for each session, its card: title, folder, status word, plan progress, and the rows in progress and next;
  • the open asks: the question and its options, or the permission and its one-line summary. The full request (the tool's arguments) never leaves the Mac;
  • the last 200 events of each session, each cut to 4 KB;
  • the name of each Mac, and each phone's name, platform and push token.
• How long it stays: a closed session is deleted after 3 days and a closed ask after 1 day. A session's events are deleted with it, and only the newest 200 are ever kept.
• Revoking a phone (oceancode companion revoke <id>) deletes its device token and closes its connection at once.

Commands

Details and exit codes: 21 · oceancode companion.

See also

• 19 · Ocean pager — /companion among the Ocean session commands.
• 21 · CLI reference — the companion subcommands.
• 15 · Platform mode — the Ocean sign-in in every build.