Slack

Slack enables two separate features:

• Slack → Agentastic: a mention or DM reaches the main Mac app, which starts or continues an agent task.
• Agentastic → Slack: attaching the Slack plugin gives the agent Slack tools on its own machine. Local, remote, and container agents call Slack directly.

The Mac is needed to configure a launch and to receive incoming Slack requests. Once the outbound plugin is deployed, its Slack API calls do not use the Mac app, an SSH callback, or a shared-file message queue. The agent still follows its provider's normal lifecycle and approval policy.

Connect your workspace#

Open Settings → Plugins → Slack. The message at the top tells you the next missing step. Start with 1. Connect your workspace; incoming messages are optional and have their own setup below.

1. Click Copy app manifest, then Open Slack apps. For a new app, choose Create New App → From a manifest and paste it. For an existing app, open App Manifest and apply the supplied configuration. Preserve your app's name and bot display name if you have already customized them. The same manifest is available here.
2. In your Slack app's OAuth & Permissions, choose Install to Workspace (or Reinstall to Workspace after changing scopes) and allow access.
3. On that same page, under OAuth Tokens for Your Workspace, copy the Bot User OAuth Token starting with xoxb-.
4. Paste it into Agentastic's Bot User OAuth Token field and click Connect workspace. Agentastic verifies the token before saving it in Keychain. The connected workspace's name appears once verified.
5. Invite the bot to the channels the agent should access. Attach Slack in the agent's plugin menu and start a new run. Existing runs retain their launch-time plugin configuration.

Why the credentials in Basic Information look different#

Basic Information → App Credentials identifies the Slack app itself. The workspace installation creates the bot token that Agentastic needs. Creating an app alone does not complete installation.

What Slack shows	Where it belongs
App ID	Identifies your Slack app; Agentastic does not ask you to enter it.
Client ID and Client Secret	Used by a hosted OAuth service to exchange an installation code for a token. Agentastic's current setup uses your own app's installation token directly.
Signing Secret	Verifies incoming HTTP webhooks. Agentastic receives events using Socket Mode.
Verification Token	Deprecated by Slack; unused by Agentastic.
Bot User OAuth Token (xoxb-)	OAuth & Permissions, after workspace installation. Required for agent access.
App-Level Token (xapp-)	Basic Information → App-Level Tokens → Generate Token and Scopes. Optional; needed to receive tasks on the Mac.

If you only see Client ID, Client Secret, and Signing Secret, switch to OAuth & Permissions and complete installation. Do not paste those app credentials into the bot-token field. See Slack's token reference and installation guide.

Superset uses a hosted OAuth connection: users click Connect, then authorize Superset's Slack app. Superset's server uses its own Client ID and Client Secret to exchange the authorization code for the workspace bot token and store it. Users do not supply those credentials. Agentastic currently uses a bring your own Slack app flow, so installation and token copying are explicit steps. The required token is the same kind of bot token; the onboarding flow is different.

Agent access after connection#

Node.js 18+ must be available in the agent's environment. Agentastic's standard cloud/container image includes Node. The Slack helper is bundled with Agentastic and deployed with the plugin; it does not need an npm download or a separate public service.

Claude Code and Codex receive a slack MCP server automatically, using the same configuration delivery paths as Sentry and Linear. Other agents that can execute commands receive the portable Slack CLI. Existing user-configured MCP servers are deduplicated using the normal plugin rules.

Use Slack from an agent#

The plugin exposes these MCP tools:

Tool	Purpose
slack_status	Check the bot's identity and workspace
slack_post_message	Send a message or reply using channel, text, and optional thread_ts
slack_upload_file	Attach an image or file from the agent's machine using file_path, channel, and optional thread_ts, title, initial_comment, and alt_text
slack_list_channels	List public/private channels visible to the bot
slack_get_channel_history	Read recent messages from a conversation
slack_get_user_info	Read a Slack user profile
slack_add_reaction	Add an emoji reaction to a message

Agents may also use the CLI. AGENTASTIC_SLACK_CLI points to the deployed executable in the agent's own environment:

The local dev shim and server-managed dev 0.9.17+ delegate dev slack to that same executable:

Use the portable variable form in containers or when the remote helper has not yet been updated. The MCP server and portable CLI need only their deployed files, Node, and access to Slack; sending does not require a daemon RPC. Missing deployment or Slack API failures return errors, with no fallback through the Mac.

--channel takes a conversation ID, not a channel name. Preserve Slack timestamps as strings. Thread replies use channel/timestamp coordinates rather than a Mac-owned task ID, so another agent can reply without access to the Mac's task database.

Messages, attachments, and reactions should be sent when requested by the user, including progress updates for their Slack task. dev notify is an app-notification command where supported; it does not automatically post to Slack.

Attach images and files#

Ask an agent with Slack attached to send a screenshot, chart, or other file. It uploads the file directly from its own filesystem, including on remote servers and inside containers. Files must be nonempty regular files, at most 50 MiB each. Slack workspace policies may impose additional restrictions.

--text-file PATH can supply a multiline caption instead of the final comment argument. --file names the attachment, while --text-file names the caption file. For MCP, use slack_upload_file with the equivalent fields shown above. The response includes the shared Slack file_id.

Existing Slack apps: add the bot scope files:write under OAuth & Permissions, then Reinstall to Workspace and allow access. Reconnect Agentastic with the resulting Bot User OAuth Token and start a new agent run to receive the updated plugin. The supplied manifest already includes this permission. Slack's external upload API uses an upload ticket, byte upload, and finalization to share the file in its channel or thread.

Member names and handles#

Incoming prompts identify the requester by their Slack display name and handle, for example Adel Ahmadyan (@adel). If the display name is empty, Agentastic uses their real name, then their handle, then their ID. The stable Slack ID remains available for mentions, API calls, and access checks.

This uses Slack's users.info method and the existing users:read scope. Names are cached for 15 minutes per connection and saved with the task. A missing permission, unavailable profile, or timeout falls back to the ID so the request can still run. Agents can also use slack_get_user_info or dev slack user --user USER_ID directly. dev slack tasks includes user_name, user_handle, and user_real_name when available, alongside user_id.

Execution locations and credentials#

Agent location	Where the Slack helper executes	Where credentials are read
Local Mac	Agent-side Node subprocess on the Mac	Private local launch directory
Remote SSH/cloud	Node subprocess on the remote host	Private files under the remote home
Docker/Apple container	Node subprocess inside the container	Private files in its mounted container home

The bot token is copied to the selected execution environment, like other token-authenticated plugins. The Socket Mode app-level token stays on the Mac. Plugin files use private directories (0700) and credential files (0600); credentials do not appear in prompts, CLI arguments, MCP config text, or Git worktrees.

Changing the bot token creates a new deployment for new runs. Disconnecting the Mac's plugin stops new delivery and its incoming listener; it does not revoke copies already deployed to running agents. Revoke the bot token in Slack to invalidate those copies. Keep the deployed files available for the lifetime of the agent run.

The supplied app manifest includes these scopes:

Scope	Used for
chat:write	Sending messages and thread replies
files:write	Attaching images and files to channels or threads
channels:read, groups:read	Listing channels visible to the bot
channels:history, groups:history, im:history	Reading supported conversation history; incoming DMs
users:read	User profiles and verifying the incoming listener's app identity
reactions:write	Adding reactions
app_mentions:read	Incoming mentions

A bot with only chat:write can connect and send to known permitted channels; other tools report missing scopes when needed. Reinstall an existing Slack app after adding scopes.

Enable incoming Slack requests on the Mac#

Incoming requests use Slack Socket Mode, so the Mac does not need a public webhook URL.

1. After connecting the workspace, open 2. Receive tasks from Slack → Set up incoming messages in Agentastic.
2. In your Slack app, turn on Socket Mode. Under Basic Information → App-Level Tokens → Generate Token and Scopes, generate a token with connections:write. Paste the xapp- token into Agentastic. Both tokens must belong to the same Slack app.
3. If you configured the app manually, enable Event Subscriptions for app_mention and message.im, and enable the Messages tab in App Home. The supplied manifest includes these settings.
4. Who can start tasks defaults to Everyone (*). Any member who can mention or DM the bot in the connected workspace can start a task. To restrict access, choose Specific members and enter their Slack member IDs. In Slack, open a profile's More menu and choose Copy member ID. Separate multiple IDs with commas.
5. Choose an open Workspace for incoming tasks. Automatic works with exactly one open workspace. Requests start detached sessions there; an explicit repo: directive can choose an open local repo instead.
6. Under Agent for new Slack tasks, choose the agent, model, thinking level, and mode. Under Channel restrictions, optionally restrict channel IDs. Empty restrictions allow mentions and DMs from allowed members wherever the bot is invited; restrictions also apply to DM conversation IDs.
7. Click Start receiving. The page identifies missing settings and connection errors. Once it shows Receiving, mention your bot in Slack to try a request. Keep Agentastic running and the Mac awake/online.

Changes to incoming settings take effect with Save changes. Turn off incoming stops the listener while keeping agent access connected. Existing installations with a saved app-level token preserve their previous incoming setting; new setups start with incoming messages off. Existing member restrictions remain in place; an unset member preference defaults to *. A listening socket alone is not shown as ready if a selected specific-member list is empty or an open workspace is missing.

The * wildcard applies to members, including authorization of queued tasks and replies. It still respects the connected workspace and any configured channel restrictions. Bot-generated messages and ordinary channel messages without a mention remain excluded.

If an older build reports that Slack did not return the bot's app ID, update Agentastic and choose Reconnect in the incoming section. The updated build corrects the bot identity lookup. Both tokens must still come from the same Slack app; a mismatch is reported separately.

Choose Slack's agent, model, thinking, and mode#

In Settings → Plugins → Slack → Receive tasks from Slack → Agent for new Slack tasks, use the same controls as Agent Home: click the agent's name to choose one agent, the model chip to choose a model and thinking effort, and the mode to choose how it runs. The model popover includes descriptions and a thinking slider.

Setting	Default	Other choices
Agent	Workspace default (automatic): the workspace's saved installed-agent selection, falling back to the first installed agent	An enabled agent from your agent catalog
Model	Workspace Setting: the saved model for that agent, or its provider default when none is saved	CLI Default (provider default) or a model from the selected agent's catalog
Thinking	Workspace Setting: the saved thinking level for that agent, or its provider default	CLI Default or a thinking level supported by the selected model
Mode	Agent, with normal approval prompts	Plan or Agent (Auto-Approve) when supported by the selected agent

Choose an explicit agent to configure its model and thinking level. CLI Default clears the inherited override and lets the provider choose. Workspace Setting in the model list and Use Workspace Setting above the thinking slider restore inheritance independently. Changing the agent resets its model and thinking choices; incompatible thinking choices are cleared when changing models.

Click Save changes. The choices apply to new Slack conversations; existing threads keep their agent and launch configuration. Saving only these preferences keeps the incoming listener and running tasks active. The Chat/Terminal interface continues to follow the agent's existing launch preference.

These member/channel restrictions apply to incoming requests. Outbound plugin access is controlled by the bot token's Slack permissions and the agent's execution policy. Turning off incoming requests or omitting the app-level token does not disable the outbound plugin.

Only one app instance on a Mac listens for a given bot. Configure a single receiving Mac for each Slack app to avoid Slack distributing incoming events between machines. Any number of authorized agent environments can use the bot token for outbound operations.

Start and continue a task from Slack#

Mention the bot using its installed display name. The supplied manifest names it Agentastic; if you name it dev in Slack, use @dev instead.

The Mac creates a detached session by default and passes the request to the agent. To use an open local repository, put repo: on the first line:

Incoming tasks launch an agent in the main editor area, without switching your active repository. Open their entry under Sessions to view the conversation. Agentastic waits for installed-agent discovery before submitting the request, and thread replies continue in the same editor agent. Older builds used a sidebar draft and could report “This chat's workspace is no longer open” or “No available agents” before launch. Update the app and send a new message in the thread to retry; a failed sidebar draft is retired once its replacement editor agent is registered. Failed requests are not automatically rerun.

The repository name must exactly match one open local repo. Use its full path if names are ambiguous. This runs in that directory; ask the agent to create a worktree with dev agent create when you want isolation. Direct remote/cloud repository selection for incoming requests is not implemented in this version; the initial agent session is owned by the Mac app.

Mention the bot again in the same channel thread to continue the session. In DMs, reply in the original thread; a new top-level DM starts another session. Start a new thread to change task directories.

Agentastic posts a starting message and updates it with the final response. The task prompt includes its channel/thread coordinates for direct plugin progress updates. The final response is posted automatically, so progress updates need not repeat it. Mention the bot with status to inspect this thread's tasks or help for usage.

Task references use readable names such as dev-task-lisbon-482 in starting messages, failures, and status replies. Each request keeps its name across restarts. dev slack tasks includes that name alongside the internal id.

The first agent prompt includes the bundled dev CLI skill, covering agent creation, worktrees, repository discovery, status checks, and communicating with other agents. It also identifies the receiving app instance and tells the agent to choose an explicit repository when working outside its detached Slack session. Follow-ups reuse the guide already in the conversation; a failed first attempt receives it again on retry.

On the Mac, these separate control commands inspect feature (a):

dev agent task, dev agent create, dev repos, dev agents, and dev tail retain their existing app-control behavior. See the system CLI reference.

Delivery and recovery#

For incoming requests, the Mac persists admission before acknowledging Slack and deduplicates event IDs and message timestamps. Up to three independent threads run concurrently, with follow-ups queued within each thread. After an app restart, queued work resumes and interrupted work is marked for inspection rather than automatically rerun. Pending final responses are retried, updating a known Slack message where possible.

For outbound plugin calls, the target executes the request directly. Explicit rate limits receive bounded retries. Network failures after a write report uncertain delivery and are not automatically reposted; check the Slack thread before retrying. The plugin does not require a Mac heartbeat or queue service.

Incoming text mentions and DMs are supported. The Mac includes recent Agentastic exchanges from the thread but does not automatically download attachments, unfurl links, or read arbitrary channel history. Agents with the outbound plugin can request channel history using its MCP tool or CLI. Socket Mode apps cannot currently be listed in the public Slack Marketplace; the supplied manifest is for direct installation in your workspace.