Set up Slack for Kranz missions

Before you connect

Slack is optional. Complete the repository and agent setup in your first mission first. You need permission to install a Slack app, a channel for mission updates, and a machine that can keep Kranz running.

This walkthrough uses one Kranz host, one repository, and the supplied manifest’s public-channel setup. If you already use host.repos, configure the catalog’s per-repository Slack routes; changing the terminal’s working directory does not override that catalog. See the multi-repository host reference.

The bridge uses Slack Socket Mode, so it connects outward to Slack. You do not need to expose your dashboard or open a public webhook endpoint.

1. Create and install the Slack app

1. Open Slack’s app settings, choose to create an app from a manifest, and use Kranz’s app manifest. Review the requested permissions before installing it in your workspace.
2. Under OAuth & Permissions, copy the installed app’s bot token, which starts with xoxb-.
3. Under Basic Information → App-Level Tokens, generate an app token with connections:write. This token starts with xapp-. Confirm Socket Mode is enabled.
4. Add the Kranz app to the public channel you will use. Note the channel’s Slack ID and your own Slack member ID for the configuration below.

The manifest defines /kranz, interactive buttons, the App Home tab, and public-channel thread events. Private-channel and direct-message conversations require additional Slack configuration; they are outside this walkthrough.

2. Configure the host and authorized users

On the machine running Kranz, add or merge this slack object into your user-level ~/.kranz/config.json. Preserve any existing settings. Replace every example value; the IDs are Slack IDs, not display names.

{
  "slack": {
    "botToken": "REPLACE_WITH_BOT_TOKEN",
    "appToken": "REPLACE_WITH_APP_TOKEN",
    "channel": "C0123456789",
    "allowUsers": ["U0123456789"],
    "allowAllUsers": false
  }
}

Keep tokens out of the repository and Slack messages. The bridge reads these credentials from the user-level configuration, not the repository’s .kranz/config.json. A host secret store can instead supply KRANZ_SLACK_BOT_TOKEN, KRANZ_SLACK_APP_TOKEN, and KRANZ_SLACK_CHANNEL; those environment values take precedence over the corresponding file fields.

allowUsers controls spending and mutation: creating or planning missions, approvals, steering, and configuration changes. An empty list with allowAllUsers: false authorizes nobody for those actions. Read-only commands such as status remain available to other app users, so this list is not a confidentiality boundary for mission information.

3. Start the bridge and check the connection

From the prepared repository, start one server process:

kranz serve --slack

If autoWork is enabled, the server can also start already queued missions. Review that queue before starting it.

If a Kranz server is already running, arrange a restart with --slack when it is safe to do so. Keep the host running and awake for Slack control. Missing token or channel configuration leaves the bridge disabled; inspect the terminal’s connection messages if it does not respond.

In the Slack channel’s main composer, send these commands individually:

/kranz help
/kranz status

These commands do not start an agent session. Use slash commands in the channel; use ordinary replies inside a mission’s thread.

4. Plan, approve, and follow a mission

Use /kranz new to open a form for a goal, or send a one-line goal:

/kranz new Add a GET /health endpoint with an integration test

Creating a mission starts a planning turn through your configured agent runtime. Usage and costs follow that runtime. Answer the orchestrator in the resulting thread. When the scope is ready, request the plan from the channel, replacing the example ID with your mission’s ID:

/kranz plan m-123abc

Review the plan, estimate, and acceptance criteria. Use the card’s Approve & start button to approve and begin, or Approve & queue to approve and enqueue it. These buttons bind to the plan shown on the card; a stale card is refused.

Queueing can lead to execution automatically if the host’s auto-work setting is enabled. Otherwise, an authorized operator can trigger the queue with /kranz work run. That command drains queued work; /kranz work only reports the queue.

Follow updates in the mission thread. For targeted status and control, use these commands individually:

/kranz status m-123abc
/kranz pause m-123abc
/kranz resume m-123abc

Pause is applied between worker runs; it is not an immediate process kill. Ordinary thread replies continue planning or provide guidance to a running mission. Read the recorded reason when work blocks or fails.

5. Review the result and merge

Slack carries completion summaries and controls. Use the dashboard for full transcripts, diffs, and detailed validation evidence. A completed mission’s Merge action runs the same repository merge gates as the dashboard. The ordinary merge stays local; push reviewed work through your normal Git workflow.

Optionally set slack.dashboardUrl to your dashboard’s base URL to add dashboard links to mission messages. That URL must be reachable from the device opening it: http://127.0.0.1:4560/ works only on the Kranz host itself. Slack connectivity does not make a local dashboard reachable from your phone.

If commands are missing, check the app installation and manifest. If replies in threads are missing, check app channel membership and the manifest’s message subscription. If an action says “not authorized,” check the invoking member’s ID in allowUsers.

Continue with reviewing agent changes, or consult the current Slack command reference for backlog and configuration commands.