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:

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.