Codumentor logo Codumentor

Slack Integration Plugin

Connects Codumentor to a Slack workspace in both directions:

Uses Slack Socket Mode, so you do not need a public URL or webhook receiver.

Requirements

A Slack app with Socket Mode enabled (see Slack App Setup). The slack-bolt package is already a Codumentor dependency.

Configuration

plugins:
  - module: codumentor.plugins.slack_integration
    class: SlackIntegrationPlugin
    args:
      enabled: true
      bot_token_env: SLACK_BOT_TOKEN     # env var holding the xoxb- token
      app_token_env: SLACK_APP_TOKEN     # env var holding the xapp- token
      service_user_id: slack-bot         # Codumentor user that owns Slack-originated conversations

Both tokens must be present in the environment when the API server starts. If either is missing, the plugin loads in degraded mode — no listener, no tools, no crash — and logs a warning.

Full configuration

plugins:
  - module: codumentor.plugins.slack_integration
    class: SlackIntegrationPlugin
    priority: 50
    args:
      enabled: true
      bot_token_env: SLACK_BOT_TOKEN
      app_token_env: SLACK_APP_TOKEN
      service_user_id: slack-bot
      slash_command_name: codumentor              # Slack-side command is /codumentor
      enabled_triggers: [app_mention, im, slash_command]
      target_agents: main                         # which agent types get the tools
      auto_reply_to_thread: true                  # post final reply back to Slack
      # Inbound context-reading (see "Reading the conversation"):
      read_thread_context: true                   # read the thread a mention lands in
      thread_context_limit: 20                    # how many recent messages to keep
      read_channel_context: false                 # opt-in: also read channel history
      channel_context_limit: 20
      context_ranking: off                        # off | jev (rank context by relevance)
      context_top_k: 8                            # messages to keep when ranking=jev
      jev_api_key: ''                             # ${secret:jev_key} or set TYPESAFE_API_KEY
      jev_model: jev-latest
      jev_base_url: https://api.typesafe.ai/v1
      jev_timeout: 4.0

Parameters

ParameterTypeDefaultDescription
enabledbooltrueMaster on/off switch.
bot_token_envstringSLACK_BOT_TOKENEnvironment variable holding the bot user OAuth token (xoxb-...).
app_token_envstringSLACK_APP_TOKENEnvironment variable holding the app-level token (xapp-...) with connections:write scope, used for Socket Mode.
service_user_idstringslack-botCodumentor user that owns Slack-originated conversations. Must be a real user in your auth provider (with auth.provider: none, any string is accepted on first use).
slash_command_namestringcodumentorSlash-command name (without the leading /). Must match the command configured in the Slack app.
enabled_triggerslist[app_mention, im, slash_command]Which Slack events start an agent turn. Allowed values: app_mention, im, slash_command. Unknown values are dropped.
target_agentsstringmainWhich agent types receive the Slack tools. One of main, subagent, all.
auto_reply_to_threadbooltrueWhen true, the agent's final response is posted back into the Slack thread that triggered the turn. Set to false if you want the agent to decide via slack_send_message.
read_thread_contextbooltrueRead the thread a mention lands in (and DM history) before answering, so the agent sees the conversation, not just the triggering message.
thread_context_limitint20How many recent messages to keep when reading thread/DM context (1–100).
read_channel_contextboolfalseAlso read recent top-level channel activity for a top-level mention. Off by default — it is a second, rate-limit-sensitive Slack read per message.
channel_context_limitint20How many recent channel messages to keep when read_channel_context is on (1–100).
context_rankingstringoffHow to choose which fetched messages to inject: off keeps the most recent N; jev ranks them by relevance to the query and keeps the top-K. Unknown values clamp to off.
context_top_kint8Number of messages to keep when context_ranking: jev (1–50).
jev_api_keystring""Jev API key, used only when context_ranking: jev. May carry a ${secret:<name>} placeholder; falls back to the TYPESAFE_API_KEY env var.
jev_modelstringjev-latestJev model id.
jev_base_urlstringhttps://api.typesafe.ai/v1Jev API base URL.
jev_timeoutfloat4.0Per-request Jev timeout in seconds (0.5–30).

Tokens are read from the environment, never from the YAML file. Only the env-var names are recorded. If a token rotates, restart the API server with the new value in the environment.

Tools

slack_send_message

Post a message to a Slack channel or thread.

ParameterRequiredDescription
channelYesChannel id (C…/D…/G…), #channel-name, or user id (U…) for a DM.
textYesMessage text. Slack mrkdwn is supported.
thread_tsNoIf supplied, the message is posted as a threaded reply under the message at that ts.

slack_add_reaction

Add an emoji reaction to an existing Slack message.

ParameterRequiredDescription
channelYesChannel id where the message lives.
tsYesTimestamp (ts) of the target message.
emojiYesEmoji name without colons, e.g. thumbsup, eyes.

Calling this on a message that already has that reaction is treated as success, so the agent can retry safely.

slack_read_thread

Read a Slack thread (the root message and its replies), oldest to newest. Reads are bounded (up to ~1,000 messages across a few pages); very long threads are returned with an "incomplete" note. Lets the agent understand the conversation a message sits in.

ParameterRequiredDescription
channelYesChannel id where the thread lives.
tsYesThe thread's root ts (thread_ts); any message ts in the thread also works.

slack_read_channel

Read the most recent top-level messages in a channel or DM (not thread replies).

ParameterRequiredDescription
channelYesChannel id to read.
limitNoHow many recent messages to fetch (default 20, max 100).

slack_search_messages (temporarily disabled)

Temporarily not registered: Slack search.messages requires a user token (xoxp-…), but the plugin is configured with a bot token only (xoxb-…), so the call always fails with a token-type error.

Search Slack for past messages by keyword, scoped to what the bot can see.

ParameterRequiredDescription
queryYesSearch keywords (Slack search syntax supported).
channelNoRestrict the search to one channel.
limitNoMax results (default 10, max 20).

The read tools are read-only (is_write is false), so they are never gated by the write-tier approval flow, and they are offered to whichever agents target_agents selects.

Reading the conversation

By default the agent does not only see the message that addressed it — it sees the
conversation around it. This is what lets it answer "what did Alice just say?"
instead of being blind to the channel.

Mechanics:

Inbound triggers

app_mention

When someone mentions the bot in a channel (@codumentor what files are…), an agent turn starts whose conversation is bound to that Slack thread. Later mentions or replies in the same thread continue the same conversation.

im (direct messages)

When someone DMs the bot, each DM thread is a separate Codumentor conversation. The bot's own messages are ignored so the auto-reply does not ping-pong.

slash_command

/codumentor <prompt> posts an in-channel acknowledgement (/codumentor … _thinking…_) and starts an agent turn whose reply is threaded under the ack. The slash-command name is configurable.

Slack App Setup

  1. Create a new Slack app at (from scratch).
  2. Socket Mode → Enable Socket Mode → generate an app-level token with the connections:write scope. This is the xapp-... token (SLACK_APP_TOKEN).
  3. OAuth & Permissions → add bot scopes: - app_mentions:read - chat:write - im:history, im:read, im:write (for DM trigger) - commands (for slash command) - reactions:write (for the slack_add_reaction tool)
  4. Event Subscriptions → enable events, subscribe the bot to app_mention and message.im.
  5. Slash Commands → create /codumentor (or whatever you set slash_command_name to). The request URL is not used by Socket Mode but Slack still requires a placeholder — any URL is fine.
  6. Install to Workspace → grants the xoxb-... bot token (SLACK_BOT_TOKEN).
  7. Invite the bot to any channel where you want it to respond.

Behavior

Limitations