Slack

Slack is the Control Channel for Tarsk: mention the bot in a bound Slack channel, continue in the Slack thread, and get the assistant’s final reply back in Slack. Full tool output, diffs, and streaming stay in the Tarsk UI. Chat history in Tarsk shows those prompts as normal user turns, labeled with who sent them.

The channel only works while Tarsk is running (desktop app, npx tarsk, or npx tarsk --server). There is no always-on companion process and no Tarsk-hosted shared Slack app.

Prerequisites

• Tarsk running with at least one project
• A Slack workspace where you can create and install apps
• Permission to install a custom Slack app (workspace admin approval may be required)

Step 1: Create the Slack app from Tarsk’s manifest

1. In Tarsk, open Settings → Slack and click Copy app manifest.
2. Open api.slack.com/apps → Create New App → From a manifest.
3. Pick your workspace, paste the JSON, and create the app.
4. Click Install to Workspace and approve the requested scopes.
5. Under OAuth & Permissions, copy the Bot User OAuth Token (xoxb-…).
6. Under Basic Information → App-Level Tokens, click Generate Token and Scopes, add the connections:write scope, and copy the token (xapp-…).
7. Confirm Socket Mode is enabled (the manifest turns it on).

Use a separate Slack app (and tokens) for each Tarsk instance. Do not reuse one bot across machines.

What the manifest configures

Area	Value
Socket Mode	Enabled (outbound WebSocket; no public URL required)
Bot events	app_mention, message.channels, message.groups
Bot scopes	Mentions, channel history/read, chat write, files read, reactions write, users read

Step 2: Connect Tarsk

1. Open Settings → Slack.
2. Paste the Bot User OAuth Token and App-Level Token.
3. Click Save in the Tokens row.
4. Confirm the page shows the bot username, workspace, and bridge as running.

If the bridge shows stopped, save the tokens again and check that Tarsk is still open. Use Settings → Logs to diagnose Socket Mode errors.

Step 3: Bind a channel to a project

1. In Slack, invite the bot to the channel (/invite @YourBotName).
2. In Tarsk Settings → Slack, choose the channel and a Tarsk project.
3. Click Bind channel.

Each channel maps to at most one project. Multiple channels may bind to the same project. Unbound channels are ignored. DMs with the bot are not supported.

Re-open Settings → Slack after inviting the bot if the channel picker was empty — Tarsk lists channels the bot can see once the bridge is connected.

Step 4: Send your first prompt

In a bound channel, mention the bot with a prompt:

@Tarsk Summarize the last commit and suggest a test to add.

Tarsk:

1. Auto-creates and claims the channel’s default Tarsk workspace (a read-only chat on the channel’s default clone using the cheap model), opens a new Tarsk chat, and replies in a Slack thread under your message
2. On a new clone, posts a setup notice, then Branch {name} · path {folder}
3. Posts a status note naming the model (with an Open in Tarsk link when possible)
4. Replies in the Slack thread with the assistant’s final text

Continue the conversation by replying in the same Slack thread without a mention. Later top-level @Tarsk mentions start a new Slack thread and a new Tarsk chat on the same channel-default clone (they do not create a new workspace).

@Tarsk branch is optional. Use it for an isolated repo clone with full tools and the smart model. From the channel composer, it starts a new Slack thread. Within a Slack thread, it moves that chat to the new clone:

@Tarsk branch Try a different approach to the auth refactor

Your Slack messages appear in Tarsk chat as user turns labeled with the Slack display name. Images and common text/file attachments are included when Slack provides download URLs.

Control commands

In a Tarsk Slack thread, reply with exactly one of these — or @ the bot with the same word:

Reply / mention	Purpose
help	Help text
status	Bound project and bridge status
stop	Stop the busy turn in this thread
models	List enabled models and switch this thread’s model
tasks	List project tasks; use buttons to implement, delete, or apply a skill
skills	Pick a skill to prompt with
branch	Create an isolated repo clone with full tools; not required before other prompts

You can also @ the bot from the channel composer (for example @Tarsk status before starting a thread).

Permissions and approvals

If the agent needs shell/web approval or an open-ended question, Slack posts a short notice with an Open in Tarsk link. Resolve those in the Tarsk UI — Slack does not show Allow/Deny buttons in v1.

Busy threads

If Tarsk is running a turn on the target workspace, it rejects new prompts for that workspace until the turn finishes or you stop it. Slack threads that share the channel-default clone share this busy check. Use @Tarsk branch to create a separate workspace for parallel work.

Common pitfalls

Symptom	What to check
Bridge stopped / not configured	Both tokens saved? Tarsk still running? Re-save tokens and check Settings → Logs.
Bot ignores the channel	Channel bound in Settings? Bot invited (/invite)?
No 👀 reaction on prompts	Update the Slack app with the latest Tarsk manifest (adds reactions:write), then reinstall the app to the workspace so the bot token picks up the new scope.
“Still working…”	Wait, or reply stop inside that Slack thread.
Empty channel picker	Bridge running and bot invited to channels, then refresh Settings → Slack.
DM with no useful reply	DMs are not supported; use a bound channel.
Permission / ask-user stuck	Open the Tarsk UI link from Slack and answer there.

Security notes

• Keep Bot and App-Level tokens private. Clearing tokens in Settings stops the bridge.
• Anyone in a bound Slack channel can prompt Tarsk against that project’s workspace and tools.
• Pairing is not used; Slack channel membership is the access control.

Related

• Settings Overview
• Logs — bridge diagnostics
• Projects — add projects before binding channels
• Tasks — what tasks operates on