For AI agents: an index of this guide is available at https://www.plungeai.com/guide/llms.txt. Append .md to any page URL, or send Accept: text/markdown, to get markdown. The developer documentation is at https://www.plungeai.com/docs/llms.txt.

Documentation Index: fetch the complete documentation index at /llms.txt. Use this file to discover all available pages before exploring further.
Feedback

Slack Remote lets you follow and drive your sessions from one Slack channel, from your phone or anywhere else. Every session has its own thread: you see what the agent wrote before it asks, answer its questions and permissions with a button or a reply, read its whole final answer, and send it the next prompt. The engine dials out to Slack over Socket Mode, so the Mac needs no open port and no relay.

Slack never slows a session down. The bridge is a separate task that reads the engine's events after they happen; the agent never waits for a Slack call. A session that asks waits for the first answer, from the window or from Slack, whichever comes first.

A thread per session

When a session gets its first prompt, the engine posts the session's card at the channel's top level: #<code> · <title> · <folder> (its short code, title and folder), ▶ and the latest prompt, and a status line. Everything about that session goes in the card's thread:

In the threadShown in the channel too
A prompt typed in the window, as ▶ <prompt>No
A permission ask, with the agent's text before it, what it asks for and the buttons Allow once, Always and DenyYes
A question ask: one message per question, the first with the agent's text before itThe first message
✅ Done and the turn's whole final reply (up to about 12,000 characters, its start kept)Yes
⛔ Blocked — <reason> and whatever the turn wrote, when it stops on an error, a refusal or a boundYes

The messages shown in the channel are the ones that reach your phone as a notification; the rest wait in the thread. The card's status line is edited in place: ⏳ Working — bash: run the tests · plan 3/7 → Build, ❓ Waiting for you, ✅ Done, ⏹ Stopped or ⛔ Blocked. The tool it names and the plan progress are brought up to date at most every ten seconds; an edit notifies no one.

The agent's text before an ask is the text of the step that asked: the sentences the model wrote right before it called the tool. A long one keeps its end, where the question's reason usually is. A permission names what it asks for: a command with the model's own description of it (and its folder, and a warning when it reaches outside the project), the files an edit touches, the page a fetch opens, the words a search sends, the helper a task starts. Model text is shown with its formatting: bold, lists, links, code blocks; a table becomes a code block with its columns aligned.

A question shows its options numbered, each with its description, its reason and its preview when the agent gave them. A question with one to five options that takes one choice gets a button per option.

An ask raised by a sub-agent is posted in its root session's thread; a sub-agent's prompts and finished turns post nothing. Once an ask is answered, in Slack or in the window, its message loses its buttons and gains a line saying how it ended: Allowed once from Slack, Denied in the window, Answered: <text>, Expired after 30 min or No longer open. A window that opens a session later posts in the same thread. Delete a card and the next message starts a new thread.

Answering from Slack

Press a button, or reply in the session's thread:

Reply in the threadOn a permission askOn a questionWith no open ask
yes, y, allow, okAllow onceThe answerThe next prompt
alwaysAlways allowThe answerThe next prompt
no, n, deny, rejectDenyThe answerThe next prompt
stopInterrupts the sessionInterruptsInterrupts
Any other textDeny, with the text as the correctionThe answerThe next prompt

Case and a trailing . or ! do not matter (Yes. is yes), and a leading mention of the bot is dropped. A reply goes to the session's oldest open ask: a permission first, else a question. On a question, a number picks that option (2), so does its label or the start of it (stag for staging), and anything else is the answer in your own words. A reply that reached its session gets 👀. A prompt from Slack shows in the window that has the session open (Ocean TUI, Xcode), then its reply, as if typed there.

Answering several questions

An ask with several questions is posted as one message per question (Question 2 of 3). Answer each with its buttons, or reply in the thread: replies answer the questions in order, and a reply that starts with a question's number and a colon answers that one (2: staging). An answered question's message loses its buttons and shows the answer; the agent gets all the answers at once, when the last one is in. A question that takes several choices is answered with their numbers (1 3).

Talking to the channel

A message at the channel's top level, outside every thread, is read too:

MessageWhat happens
sessions (or list, status, help, ?)Lists this Mac's open sessions, to you alone: code, title, folder, state, the tool running, plan progress and a link to each thread.
off, onTurns Slack off or on for this Mac (Turning it on and off).
#UpQG run the testsrun the tests is the next prompt of the session #UpQG.
Any other textThe next prompt of the only open session; with several open, the list, and how to name one.

A prompt that reached its session gets 👀; an unknown code, or text with several sessions open, gets the list. The list and these answers are shown to you alone (Slack's Only visible to you) and are not kept.

Several windows and Macs

Every window that hosts the engine connects: plain oceancode (the TUI), oceancode acp and oceancode serve. One-shot oceancode run, goal and workflow never connect. Slack allows ten connections per app; a window past that keeps retrying. Automation that launches oceancode acp or serve unattended sets OC_SLACK=0 (Ocean Factory, Ocean Vibe and the Ocean app do), so it never takes a press or a reply meant for your windows.

Slack hands each button press or reply to one of the app's connections, whichever window that is. On one Mac that does not matter: the window that receives it hands it to the window that owns the session, through the session line, as soon as it is queued. A window cannot hand a reply to another Mac, so a reply that lands on the wrong Mac is dropped. On several Macs, give each Mac its own Slack app; the apps can share one channel. Name each app after its Mac, so its posts and its /invite are told apart: change display_information.name and features.bot_user.display_name in the manifest, for example to Ocean Code – Studio. Each Mac's connected message also names its hostname.

Setting it up

About five minutes: steps 1–3 are on Slack's app page, step 4 in the Slack app, step 5 one command in Terminal. You need two tokens and one channel id, and nothing else from Slack's pages (not the App ID, Client ID, Client Secret, Signing Secret or Verification Token).

WhatStarts withWhere in Slack
Bot tokenxoxb-Install App (or OAuth & Permissions) → Bot User OAuth Token
App-level tokenxapp-1-Basic Information → scroll down → App-Level Tokens
Channel idC (or G)The channel's details, at the bottom of About
  1. Create the app. Open this link (opens in a new tab) (Slack's Create New App with the manifest filled in), pick your workspace, choose Next, then Create. Or, at api.slack.com/apps (opens in a new tab), choose Create New App → From an app manifest and paste the manifest yourself. Nothing in the app's settings needs changing afterwards; in particular, add no scope under OAuth & Permissions (that list is complete, and a change there makes Slack ask for a reinstall).

  2. Install it and copy the bot token. In the left menu choose Install App → Install to your workspace → Allow. Copy the Bot User OAuth Token (xoxb-…). Hold both tokens in a note, not in a chat: a token pasted into a chat is in that chat's history.

  3. Copy the app-level token. Choose Basic Information and scroll down past App Credentials to App-Level Tokens. Choose Generate Token and Scopes, name it socket, choose Add Scope → connections:write (this scope exists only here, never in the OAuth list), then Generate, and copy the token (xapp-1-…). To copy it again later, click the token's name and use its Copy button; selecting the text by hand can miss the xapp-1- start.

  4. Make the channel. In the Slack app, + next to Channels → Create a channel, named for example ocean-code, set to Private, then Create. It must be private: whoever can write in the channel can run prompts on this Mac, and connect refuses a public channel. In the channel, type /invite @Ocean Code (or the name you gave the app). Click the channel's name; the Channel ID (C…, or G… for an older private channel) is at the bottom of the About tab. While there, set Notifications to All new messages, else the phone is only alerted for mentions.

  5. Connect. In Terminal, with your channel id:

    oceancode slack connect C0123456789

    It asks for the bot token, then the app-level token. Nothing shows while you paste; that is on purpose. Paste, press Enter, paste the second, press Enter. Spaces, quotes and invisible characters that copy and paste add are removed, and a token in the wrong place is named (the first token is the app-level token (xapp-); the app-level token must start with xapp-; the second token given (21 characters) does not), never shown. Scripts set SLACK_BOT_TOKEN and SLACK_APP_TOKEN instead, or pipe the two lines on stdin (the bot token first).

    connect checks the bot token, that the channel is private, then the app-level token and Socket Mode, posts Ocean Code connected from <hostname> (this Mac's hostname) in the channel, and only then stores the three and prints SLACK_CONNECT_OK team=<team> channel=<id>.

  6. Open a new window, or restart the open ones: a window reads the tokens when it starts. Then try it: give the window a prompt; the session's card shows in the channel. Ask it to run a shell command; the permission ask shows in the card's thread with its buttons, and a ✅ Done message follows with the reply. Reply in the thread to send the next prompt from your phone, or type sessions in the channel.

oceancode slack status shows the team, the bot user, the channel, whether Slack is on and whether OC_SLACK leaves the bridge on. connect again without a channel replaces the tokens and keeps the channel; oceancode slack disconnect removes them. Flags and exit codes: 21 · CLI reference.

The manifest

display_information:
  name: Ocean Code
features:
  bot_user:
    display_name: Ocean Code
    always_online: true
oauth_config:
  scopes:
    bot:
      - chat:write
      - reactions:write
      - groups:history
      - groups:read
      - channels:history
      - channels:read
settings:
  event_subscriptions:
    bot_events:
      - message.groups
      - message.channels
  interactivity:
    is_enabled: true
  socket_mode_enabled: true

chat:write posts and updates the messages and answers privately, reactions:write adds the 👀, and always_online shows the bot as present. The groups: scopes read a private channel and the channels: scopes a public one (the two :read scopes also let connect tell which the channel is); the two events deliver thread replies and top-level messages, interactivity delivers button presses, and Socket Mode carries both over the connection the engine opens, so the app needs no request URL. The app-level token's scope, connections:write, is chosen when you generate the token (step 3); a manifest cannot carry it.

An app created before reactions:write was in the manifest works the same without the 👀. To add it: on the app's page, OAuth & Permissions → Bot Token Scopes → Add an OAuth Scope → reactions:write, then Reinstall to your workspace → Allow; the bot token stays the same, so no connect is needed.

Privacy

Slack, and everyone in the channel, sees: session titles, folder names, the prompts, the permissions asked (commands with their descriptions, paths, pages), question text and options, the text the agent wrote before each ask, each turn's whole final reply, and why a turn was blocked. What you type in a thread goes to the engine and, as a prompt, to the model. Anyone in the channel can press a button or reply with the same power as you at the keyboard, so connect refuses a public channel; keep the private one to you and the bot. Each press and reply the engine carries out is logged with the sender's Slack user id (never the text).

The two tokens and the channel id are in the data dir's auth.json (mode 0600), under slack. No command prints a token and no log line carries one.

Turning it on and off

Slack is on once connected. Turn it off when you are at the Mac, and on again before you leave:

WhereOffOn
In a window (Ocean TUI)/slack off/slack on (bare /slack flips it)
In the channel, at the top leveloffon
In Terminaloceancode slack offoceancode slack on

The switch is for the whole Mac: every open window follows within two seconds, and windows started later begin in the same state. While Slack is off nothing new is posted and replies in Slack are not taken: a reply, a button or a top-level message gets a private Ocean Code on <Mac> is off for Slack answer instead, so a reply is never lost without a word. A session keeps working; its asks wait for you in the window. Turned on, the questions and permissions waiting in each window are posted, and the cards catch up. A message already in Slack is still closed when you answer its ask in the window. The tokens are kept; on needs no new connect.

OC_SLACK=0 in a window's environment keeps that one window out of Slack whatever the switch says (02 · Configuration); /slack in such a window says so. oceancode slack disconnect removes the tokens. The webhook recipe in 10 · Hooks is the one-way alternative: it posts, but you cannot answer.

Troubleshooting

ErrorCauseFix
usage: oceancode slack connect …The channel id did not come through: a word after it, or a long dash (–channel) typed in place of --channel.Type oceancode slack connect C… with the id alone after connect.
the first token is the app-level token (xapp-)The two tokens were pasted in the wrong order.Run connect again: the bot token (xoxb-) first, the app-level token (xapp-) second.
the second token is a bot token (xoxb-)The bot token was pasted twice.The app-level token is under Basic Information → App-Level Tokens (step 3).
the app-level token must start with xapp-The copy missed the token's start (xapp-1-), or it is not an app-level token.Under App-Level Tokens, click the token's name and use its Copy button.
the bot token must start with xoxb-The first paste is not the Bot User OAuth Token (xoxp- is a user token; A0… is an App ID).Copy the Bot User OAuth Token from Install App (step 2).
the channel id must start with C or GNot a channel id.Copy it from the bottom of the channel's About tab (step 4).
not_in_channelThe bot is not in the channel./invite @<your bot> in the channel, then connect again.
channel_not_foundA wrong id, or a private channel the bot is not in.Check the id (step 4) and invite the bot.
is a public channelThe channel is public: everyone in the workspace could run prompts on this Mac.Create a private channel (step 4), invite the bot and connect with its id.
invalid_auth, token_revokedA wrong bot token, a revoked one, or the app was uninstalled.Install App → Reinstall to your workspace → Allow, then copy the new Bot User OAuth Token.
missing_scopeThe app lacks a scope from the manifest.Paste the manifest again, reinstall, and connect with the new bot token.
Socket Mode refused the app tokenA wrong app-level token, one without connections:write, or Socket Mode off.Generate the token again (step 3); check socket_mode_enabled.
set both SLACK_BOT_TOKEN and SLACK_APP_TOKEN, only one token on stdinOnly one of the two tokens was given.Give both: the two variables, or two piped lines (the bot token first).
Slack shows a yellow "reinstall your app" bannerA scope was changed in the app's settings.Reinstall from the banner, then connect again with the new bot token.
SLACK_CONNECT_OK printed, but nothing reaches the channel laterThe windows were started before the connect.Close every oceancode window and start a new one (step 6).
A message typed in the channel gets no answerThe window was started before 0.8.8.75, or it has no open session on this Mac.Open a new window; type sessions to see what this Mac has open (Talking to the channel).
No 👀 on a reply that was carried outThe app was created before reactions:write was in the manifest.Add the scope and reinstall (The manifest).

A window that loses Slack reconnects on its own; a refused token stops its bridge until the next start. Its slack: log lines name the bot, the channel and Slack's error (18 · Operations).