> ## Documentation Index
> Fetch the complete documentation index at: https://www.plungeai.com/guide/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack

> 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 …


**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 thread | Shown 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 **Deny** | Yes |
| A question ask: one message per question, the first with the agent's text before it | The 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 bound | Yes |

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 thread | On a permission ask | On a question | With no open ask |
|---|---|---|---|
| `yes`, `y`, `allow`, `ok` | Allow once | The answer | The next prompt |
| `always` | Always allow | The answer | The next prompt |
| `no`, `n`, `deny`, `reject` | Deny | The answer | The next prompt |
| `stop` | Interrupts the session | Interrupts | Interrupts |
| Any other text | Deny, with the text as the correction | The answer | The 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:

| Message | What 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`, `on` | Turns Slack off or on for this Mac ([Turning it on and off](#turning-it-on-and-off)). |
| `#UpQG run the tests` | `run the tests` is the next prompt of the session `#UpQG`. |
| Any other text | The 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](#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).

| What | Starts with | Where in Slack |
|---|---|---|
| Bot token | `xoxb-` | **Install App** (or **OAuth & Permissions**) → **Bot User OAuth Token** |
| App-level token | `xapp-1-` | **Basic Information** → scroll down → **App-Level Tokens** |
| Channel id | `C` (or `G`) | The channel's details, at the bottom of **About** |

1. **Create the app.** Open [this link](https://api.slack.com/apps?new_app=1&manifest_yaml=display_information%3A%0A%20%20name%3A%20Ocean%20Code%0Afeatures%3A%0A%20%20bot_user%3A%0A%20%20%20%20display_name%3A%20Ocean%20Code%0A%20%20%20%20always_online%3A%20true%0Aoauth_config%3A%0A%20%20scopes%3A%0A%20%20%20%20bot%3A%0A%20%20%20%20%20%20-%20chat%3Awrite%0A%20%20%20%20%20%20-%20reactions%3Awrite%0A%20%20%20%20%20%20-%20groups%3Ahistory%0A%20%20%20%20%20%20-%20groups%3Aread%0A%20%20%20%20%20%20-%20channels%3Ahistory%0A%20%20%20%20%20%20-%20channels%3Aread%0Asettings%3A%0A%20%20event_subscriptions%3A%0A%20%20%20%20bot_events%3A%0A%20%20%20%20%20%20-%20message.groups%0A%20%20%20%20%20%20-%20message.channels%0A%20%20interactivity%3A%0A%20%20%20%20is_enabled%3A%20true%0A%20%20socket_mode_enabled%3A%20true%0A)
   (Slack's **Create New App** with [the manifest](#the-manifest) filled in), pick your workspace,
   choose **Next**, then **Create**. Or, at [api.slack.com/apps](https://api.slack.com/apps), 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:

   ```bash
   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](/oceancode/cli-reference#oceancode-slack).

## The manifest

```yaml
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:

| Where | Off | On |
|---|---|---|
| In a window (Ocean TUI) | `/slack off` | `/slack on` (bare `/slack` flips it) |
| In the channel, at the top level | `off` | `on` |
| In Terminal | `oceancode slack off` | `oceancode 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](/oceancode/configuration)); `/slack` in such a window says so. `oceancode slack disconnect`
removes the tokens. The webhook recipe in [10 · Hooks](/oceancode/hooks#recipe-slack-incoming-webhook) is the one-way
alternative: it posts, but you cannot answer.

## Troubleshooting

| Error | Cause | Fix |
|---|---|---|
| `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 G` | Not a channel id. | Copy it from the bottom of the channel's **About** tab (step 4). |
| `not_in_channel` | The bot is not in the channel. | `/invite @<your bot>` in the channel, then `connect` again. |
| `channel_not_found` | A wrong id, or a private channel the bot is not in. | Check the id (step 4) and invite the bot. |
| `is a public channel` | The 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_revoked` | A 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_scope` | The app lacks a scope from the manifest. | Paste the manifest again, reinstall, and connect with the new bot token. |
| `Socket Mode refused the app token` | A 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 stdin` | Only 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" banner | A 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 later | The 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 answer | The 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](#talking-to-the-channel)). |
| No 👀 on a reply that was carried out | The app was created before `reactions:write` was in the manifest. | Add the scope and reinstall ([The manifest](#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](/oceancode/operations)).
