Connect Slack

For people running tuckit themselves

This page walks through creating a Slack app and connecting it to your own tuckit instance. On app.tuckit.dev the Slack app belongs to that deployment, and Slack isn’t available there yet.

What it does

Mention the bot in a Slack thread and it reads that thread, works out what you’re asking for and replies in the thread with what it did. It can file a new card, or add a note to a card that already exists. It can also set up a new area to file cards under. If a thread doesn’t say clearly enough what you want, it asks you rather than guessing. Paste a tuckit link into any channel and it unfurls into a preview, the same way a Linear or GitHub link does. That’s the whole surface: everything it does starts with a mention or a pasted link.

Create the Slack app

Go to api.slack.com/apps → Create New App → From an app manifest, pick your workspace, and paste this in. Replace <YOUR-TUCKIT-DOMAIN> with the host your tuckit instance is reachable at. It’s the only thing you need to edit.

display_information:
  name: tuckit
  description: Turn a Slack thread into board state.
features:
  bot_user:
    display_name: Tuckit
    always_online: true
  slash_commands:
    - command: /tuckit
      url: https://<YOUR-TUCKIT-DOMAIN>/slack/command
      description: Connect your tuckit account
      usage_hint: connect
  unfurl_domains:
    - <YOUR-TUCKIT-DOMAIN>
oauth_config:
  redirect_urls:
    - https://<YOUR-TUCKIT-DOMAIN>/slack/oauth/callback
  scopes:
    bot:
      - app_mentions:read
      - chat:write
      - channels:history
      - groups:history
      - links:read
      - links:write
      - commands
settings:
  event_subscriptions:
    request_url: https://<YOUR-TUCKIT-DOMAIN>/slack/events
    bot_events:
      - app_mention
      - link_shared
  org_deploy_enabled: false
  socket_mode_enabled: false

Don’t install it to your workspace from this dashboard. That step happens later, from inside tuckit, so the OAuth handshake reaches tuckit’s own callback instead of stopping at Slack. For now, just open Basic Information and copy the Client ID, Client Secret and Signing Secret. You’ll need all three next.

Point tuckit at it

Set these on your tuckit instance and restart it:

SLACK_CLIENT_ID=...
SLACK_CLIENT_SECRET=...
SLACK_SIGNING_SECRET=...

Slack integration stays off until all three are set. No Slack routes are mounted, the Settings entry included, so there’s no partial state in between to debug.

Connect the two workspaces

Two things are called a workspace on this page. Slack’s is the place your team chats; tuckit’s is the board. This step ties one to the other.

As a tuckit workspace admin, go to Settings → Slack and click Connect to Slack. It is a one-time step, done by whoever administers the board.

Connect your own account

Mentioning the bot before you’ve connected gets you an ephemeral “Connect your tuckit account” message instead of an answer. Nobody’s identity gets inferred from their Slack profile. Click it, log into tuckit (or you’re already logged in and it’s immediate), and every card the bot creates for you from then on carries your name.

Mention it

@tuckit file this as a card in the billing area

It reads the thread, does what it can, and edits its own reply in place to show the result, confined to the one thread you mentioned it in. The reply names each card it wrote and links straight to it.

Adding to something that already exists works the same way, by naming the card:

@tuckit add what we decided here to TP-118

Writing new cards, notes and areas is the whole of what a mention can do. Marking a card shipped stays a decision you make in tuckit, on the card itself.

What tuckit does not ask for

This list is worth reading even if you never touch the manifest by hand. It’s the actual answer to “what can this app see.”

• users:read and users:read.email: tuckit reads no Slack profiles at all. The name on a card is the name on the tuckit account you connected yourself, so linking happens when you click a button while logged in, never by matching email addresses. Slack’s email field is set by the Slack workspace and unverified by Slack itself. Its admin can put anything they want in it. Trusting it as identity evidence would let an admin write to the board as someone else.
• message.channels / message.im: these push a copy of every message in every channel the bot is in to your server, whether anyone talked to it or not. tuckit reads a thread with conversations.replies only at the moment someone actually mentions it, pulling that one thread on demand instead of receiving every message as it happens.
• reactions:write: the bot doesn’t add emoji reactions to anything in Slack.

Refusing those scopes has one visible consequence: the bot does nothing in DMs. With no im:history scope, Slack never delivers it a direct message’s content, so a DM produces silence by design.

The model key is a separate switch

ANTHROPIC_API_KEY is optional and independent of the three settings above:

# Optional. Without it, install and link unfurling still work.
# Only @mentions are unavailable.
ANTHROPIC_API_KEY=...

Without it, you can still connect the two workspaces, connect your own account, and get link previews. What you lose is the part that reads a thread and turns it into intents. Mentioning the bot does nothing until a key is set.