takopi-slack-plugin 0.2.0

Slack transport plugin for Takopi.

takopi-slack-plugin

slack transport plugin for takopi. socket mode only, replies in threads, and stores per-thread context + resume tokens.

features

• socket mode only; listens in a single channel or dm
• thread sessions (context + resume tokens) stored at ~/.takopi/slack_thread_sessions_state.json
• slash commands + message shortcuts for overrides and plugin commands
• cancel button on progress messages
• message overflow: split or trim long responses
• file transfer: upload files into a project or fetch files/directories back

requirements

• python 3.14+
• takopi >=0.20.0
• slack bot token with chat:write, commands, app_mentions:read, and the matching history scopes for your channel type (channels:history, groups:history, im:history, mpim:history)
• for file transfer, add files:read and files:write
• slack app token (xapp-) with connections:write

install

install into the same python environment as takopi.

uv tool install -U takopi --with takopi-slack-plugin

or, with a virtualenv:

pip install takopi-slack-plugin

setup

create a slack app and enable socket mode.

1. create an app-level token with connections:write
2. add the bot scopes listed above and install the app
3. enable events for app_mention plus the right message.* event for your channel type
4. enable interactivity & shortcuts, create a slash command (for example /takopi), and optionally add dedicated commands like /takopi-preview for common plugins plus message shortcuts with callback id takopi:<plugin_id>
5. invite the bot to the target channel

add to ~/.takopi/takopi.toml:

transport = "slack"

[transports.slack]
bot_token = "xoxb-..."
app_token = "xapp-..."
channel_id = "C12345678"
message_overflow = "split"

[transports.slack.files]
enabled = false
auto_put = true
auto_put_mode = "upload"
uploads_dir = "incoming"

set message_overflow = "trim" if you prefer truncation instead of followups.

if you use a plugin allowlist, enable this distribution:

[plugins]
enabled = ["takopi-slack-plugin"]

usage

takopi --transport slack

if you already set transport = "slack", takopi is enough.

directives are optional. use /project and @branch in the first line to target a project or worktree; otherwise the run uses the default takopi context.

inline command mode: if the remaining prompt includes a /command that matches a registered command plugin, the slack bridge dispatches it instead of running the engine.

example (inline command):

@takopi /zkp2p-clients @feat/login /preview start 3000 --dev "pnpm --filter @zkp2p/web dev -- --host 127.0.0.1 --port {port}"

example (worktree):

@takopi /zkp2p-clients @feat/web/monad-usdt0 add a retry to the api call

thread replies reuse stored context, so you can reply without repeating directives.

slash command built-ins (via /takopi <command> or /takopi-<command>):

/takopi status
/takopi engine <engine|clear>
/takopi model <engine> <model|clear>
/takopi reasoning <engine> <level|clear>
/takopi session clear

message shortcuts pass the selected message text as arguments to the plugin command identified by takopi:<plugin_id>.

progress messages include a cancel button; enable interactivity & shortcuts so clicks are delivered in socket mode.

file transfer (requires files:read + files:write scopes):

/file put path/to/file.txt
/file get path/to/dir/

attach a file to /file put ... to upload it. audio file uploads can be uploaded like any other file. when auto_put_mode = "prompt", captions are used as prompts and include an [uploaded files] annotation. file transfers require a project context; use /project or @branch first.

for opinionated gating, see docs/AGENTS.example.md and docs/GATING_README.md, and customize ~/.codex/AGENTS.md.

license

mit