# Slack

Connect Slack to get agent updates in a channel, and to start agent sessions by mentioning **@iKanban**.

Everything happens on **Agent settings → Git connections** (the Connections page), in the **Communication** card.

## What Slack does

- **Start a session from Slack.** Post `@iKanban fix the failing login test` in a channel the bot is in. iKanban creates an agent session in that channel's team (or the default team) and replies in the thread with its link. To pick another agent, put its name first: `@iKanban copilot: add tests for the parser`. Claude is the default.
- **Claude runs on a laptop, not on an API key.** A Claude session from Slack runs on the laptop of the person who connected Slack, in their iKanban desktop app, with their own Claude Code sign-in (set up once in **Connections → This laptop**). If that app is closed, the reply says **Queued** and the work starts when it opens. Copilot and Gemini still run on GitHub for now.
- **Live progress in the thread.** The bot's first reply turns into a status line that updates as the agent works: ⏳ Working · steps · time, and the last few actions (Read …, Ran …, Edited …). The same steps show live on the session page. GitHub runs show only the start and the end.
- **The answer in the thread.** When the agent finishes, its answer is posted as a reply in the same thread (with the session link), and the status line changes to ✅ Done, ❌ Failed or 🔀 Pull request opened. Sessions not started from Slack post their outcome in the team's routed channel, or the default channel.
- A bare `@iKanban` makes the bot reply with how to use it. It's the safe way to check that Slack reaches iKanban.

## Which steps are yours

- **Slack shows Connect**: this server already has its Slack app. Do **Connect and configure** below (2 minutes, workspace admins).
- **Slack shows Not set up**: this server has no Slack app yet. Do the one-time **Server setup** first (about 10 minutes), then Connect.

## Connect and configure (workspace admins)

1. Click **Slack → Connect**. Slack opens **Allow the "iKanban" app to access Slack**.
2. Check the workspace under **Where do you want to use "iKanban"?**, then **Allow**. You land back on Connections with **Slack · Connected**.
3. Click **Slack → Configure** and choose the defaults:
   - **Default updates channel**: a public channel, or *Don't post updates*.
   - **Default sessions team** and **Project**: where sessions started from Slack are created.
4. Optional: add **Channel routes** so each team has its own channel (see below).
5. **Save**, then reopen **Configure** to check that your choices stuck.
6. In Slack, in each channel you picked: `/invite @iKanban`, then post a bare `@iKanban`. The bot replies in the thread.

Sessions started from Slack are created as the admin who connected Slack: Claude runs on that person's laptop (keep the iKanban desktop app open there), and Copilot/Gemini use their GitHub connection. **Disconnect** (in Configure) removes the connection: Slack stops posting and mentions are ignored.

## Route channels to teams

One Slack workspace can serve several iKanban teams, each in its own channel. In **Slack → Configure → Channel routes**, click **Add route** and pick a **Channel**, a **Team** and a **Project**. For example:

| Channel | Team | Project |
|---|---|---|
| `#ikanban-dev` | iKanban | ai-agent |
| `#support` | SupportTeam | triage |

What a route does:
- **Updates:** a team's agent updates post to its routed channels. If a team has no route, its updates go to the default channel.
- **Mentions:** `@iKanban` in a routed channel creates the session in that channel's team and project.
- **Unrouted channels:** mentions there use the default team. With no default either, the bot replies that the channel isn't linked yet.

Rules:
- One route per channel.
- A team can have several channels.
- Each route's project must belong to its team.
- The team must have at least one **Feature**: every session belongs to one. Save refuses a team without Features.
- The project needs a **GitHub repository linked**, or sessions are created but no agent can start (the bot says "No GitHub repository linked").
- Saving replaces the whole list.
- Invite the bot to every routed channel (`/invite @iKanban`).

## Server setup (once per iKanban server)

Click **Slack → Set up**. The dialog has everything, including **Copy setup prompt**: paste it into Claude Code (it drives Chrome with Claude in Chrome), or into Codex or any agent with Playwright MCP or Chrome DevTools MCP. The agent clicks through Slack and asks you before each change. It never handles the secrets.

By hand:

1. **api.slack.com/apps → Create an App → From a manifest → Continue.**
2. The editor opens on **JSON**. Click **YAML**, select all, and **paste** the manifest from the dialog (**Copy manifest**).
3. Pick your workspace → **Next**. **Review your app** shows: starts on an @mention, 4 things it can do, 1 it responds to.
4. **Create and Install**. It creates the app *and* installs it. Wait about 20 seconds while the button is grey, and click it once.
5. On **iKanban is ready!**, skip the Slack CLI steps and click **Go to App Settings** (opens a new tab).
6. **Basic Information → App Credentials**: note the **Client ID**. Store **Client Secret** and **Signing Secret** in your secret store (the dialog has a no-echo command for iKanban's AWS servers). The server needs `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET` and `SLACK_SIGNING_SECRET`; whoever runs the server adds them and redeploys.
7. Once the server has them, open **Event Subscriptions**. It shows *Your URL didn't respond*:
   - Click **Retry** until it shows **Verified ✓**.
   - Check that **app_mention** is listed under **Subscribe to bot events**.
   - Click **Save Changes**.
8. Back in iKanban, Slack now shows **Connect**. Continue with **Connect and configure** above.

## Don't

- **Don't close the iKanban desktop app on the laptop that runs Claude** and expect a quick answer. Slack sessions for Claude wait (**Queued**) until that app is open again.
- **Don't set up API keys or GitHub secrets for Claude.** It runs with the laptop's Claude Code sign-in (Connections → This laptop).
- **Don't write the scope as `app_mentions.read`.** It's `app_mentions:read` (colon). Slack rejects the manifest with "Illegal bot scopes found".
- **Don't type the manifest.** Slack's editor auto-indents and auto-closes brackets. Paste it.
- **Don't click Create and Install twice.** The button greys out for about 20 seconds while Slack works.
- **Don't follow the Slack CLI steps** on *iKanban is ready!* (`slack login`, `slack create`, `slack run`). They're for apps you run yourself; iKanban's server is the app.
- **Don't reveal the secrets.** Don't open *Your app credentials* or click **Show** in front of anyone, a screen share or a coding agent. Never paste the secrets into chat, tickets, git or a screenshot.
- **Don't expect the events URL to verify before the server has the signing secret.** It verifies with a signed request. After the server update: **Retry**, then **Save Changes**. Retry alone isn't saved.
- **Don't connect from a tab that's been open since before an update.** If you land on a *404* after **Allow**, or Slack still says *Not connected*, close every iKanban tab and open the Connections page again. The connection itself was saved.
- **Don't test with a real request first.** A bare `@iKanban` proves events arrive without starting an agent.
- **Don't forget `/invite @iKanban`.** The bot only hears mentions in channels it's in, and that includes every routed channel.
- **Don't route a channel to a project from another team.** Each route's project must belong to its team; Save refuses it otherwise.
- **Don't route to a team that has no Features.** Sessions need one; add a Feature to the team first.
- **Don't route to a project without a repository.** The session is created but the agent can't start; link a repository to the project first.
- **Don't trust the Save toast alone.** Reopen Configure: your defaults and routes should still be there.

## Check it worked

- Connections shows **Slack · Connected · \<your Slack workspace\>**, and Configure lists your channels.
- Slack app → **Event Subscriptions**: **Verified ✓**, with `app_mention` listed.
- A bare `@iKanban` in the channel gets a reply in the thread.

## Troubleshooting

- **Slack wasn't connected** after Connect: the approval was cancelled, took more than 10 minutes, or Slack refused it. Click **Connect** again.
- **No reply to a mention**: `/invite @iKanban` in that channel, and check Event Subscriptions is **Verified**.
- **"This channel isn't linked to an iKanban team yet"**: add a route for that channel, or set a default sessions team, in **Slack → Configure**.
- **No updates in the channel**: route the team to that channel, or pick it as the default. Updates only cover sessions in this iKanban workspace.
- **A session landed in the wrong team**: check which route covers the channel the mention was posted in. Routed channels win over the default.
- **Only workspace admins and owners** can connect or change Slack; others see **Not available**.