
sockdock
io.github.iwamatsu0430/sockdock
Manage SockDock rules: Slack posts that run Claude Code, Codex or a program on your Mac.
Documentation
SockDock for Slack
Run Slack apps locally: one Socket Mode connection, many handlers.
SockDock (sockdock) is a small gateway that runs on your Mac. It receives messages from your Slack workspace over Socket Mode — nothing needs to be reachable from the internet — and hands them to handlers you configure:
- command handlers: any program. It gets the message as JSON on stdin; its stdout is posted back to the thread.
- claude handlers: Claude Code in headless mode. Each Slack thread is one conversation that continues on every reply, limited to the tools you allow.
- codex handlers: Codex CLI in headless mode, the same way. Web search and file edits follow the rule; commands always run in Codex's sandbox.
Think of it as a power strip: Slack apps allow one socket, and SockDock lets you plug many things into it. A top-level message that matches a route (a channel, or DMs to the app, plus a condition) starts a thread; every reply in that thread goes to the same handler.
It comes with a CLI and an optional menu bar app.
SockDock is not affiliated with, created by, or supported by Slack Technologies, LLC.
Status: early development. macOS 13+ is the main target (the CLI also works on Linux).
Quick start
1. Install
With Homebrew:
brew install --cask iwamatsu0430/tap/sockdock # menu bar app
brew install --formula iwamatsu0430/tap/sockdock # CLI (macOS, Linux)
The app is not notarized by Apple, so the first time you open it, macOS stops it with “SockDock” Not Opened:
- Click Done (not Move to Trash).
- Open System Settings → Privacy & Security, scroll down and click Open Anyway.
- When asked again, click Open. From then on it opens normally.
This allows SockDock only; the rest of your Mac's protection stays on. Homebrew checks the download against the checksum recorded in the tap before installing it. See also Safely open apps on your Mac.
Or build from source. Tools are managed with mise.
git clone https://github.com/iwamatsu0430/sock-dock-slack.git
cd sock-dock-slack
mise install # Go, Node, wails3
mise run build # -> bin/sockdock
mise run app # optional: -> dist/SockDock.app (menu bar app, CLI bundled)
If you built it, put bin/sockdock somewhere on your PATH (the examples below assume sockdock is on it).
2. Create the Slack app
sockdock manifest
- Open https://api.slack.com/apps?new_app=1, choose From a manifest, and paste the manifest.
- Basic Information → App-Level Tokens: generate a token with the
connections:writescope (xapp-…). - Install App: install it to your workspace and copy the Bot User OAuth Token (
xoxb-…). - Invite the bot to every channel you want to route from:
/invite @SockDock. DMs to the app need no invite.
Optional: to show SockDock's icon on its replies, upload assets/slack-icon.png as the app icon (Basic Information → Display Information). Slack manifests can't set it.
3. Store the tokens
sockdock auth set # prompts for both tokens and stores them in the macOS Keychain
sockdock auth status
Alternatively, export SLACK_APP_TOKEN and SLACK_BOT_TOKEN, or point settings.secrets_file at a chmod 600 .env file.
4. Configure routes
sockdock init # writes a starter config with an "echo" route
mkdir -p ~/sockdock-handlers
cp examples/echo.sh ~/sockdock-handlers/ # the handler that route runs
Edit the config and replace C0123456789 with your channel's ID.
The config lives at ~/Library/Application Support/sockdock/config.yaml (Linux: $XDG_CONFIG_HOME/sockdock/config.yaml). A minimal route:
routes:
- name: echo
channel: C0123456789 # channel ID (channel details → bottom of the About tab)
starts_with: echo # posts that start with "echo"
handler:
type: command
cwd: ~/sockdock-handlers
command: ["./echo.sh"]
A route reacts to top-level posts that meet one of these conditions. Within a channel, routes are tried from the top and the first match runs (routes that are off are skipped).
| Key | Posts it runs on | groups |
|---|---|---|
starts_with: echo | Posts starting with the keyword | text: what follows the keyword |
contains: review | Posts containing the keyword | text: the whole post |
match: '^deploy (?P<env>\w+)$' | Posts matching the regular expression (RE2) | the named groups |
all_posts: true | Every post | text: the whole post |
Keywords ignore case, full-width vs half-width characters, repeated spaces and a leading mention of the Slack app. A keyword of letters and digits does not match inside a word (entry does not match entryx). Regular expressions are case sensitive. Add mention_only: true to run a route only for posts that mention the Slack app, and use channel: dm for DMs (see "DMs and mentions" below).
Check it:
sockdock check
sockdock match C0123456789 "echo hello"
5. Run
sockdock run # in the foreground (Ctrl-C to stop)
sockdock service install # or, without the menu bar app: start at login, restart on failure (launchd / systemd)
sockdock status
Post echo hello in the channel: SockDock reacts with 👀, runs the handler and replies in the thread.
Or use the menu bar app
With the app you do not need steps 3–5 above or any YAML. Open SockDock from Applications (built from source: open dist/SockDock.app or mise run gui):
- Setup (first launch): Open api.slack.com opens Slack's "create an app" page with the manifest filled in. Install the app, generate an App-Level Token with
connections:write, then paste both tokens and press Connect to Slack. The tokens are checked with Slack first and saved to the Keychain only if both work. To use a Slack app you already have, open Use a Slack app you already have in setup: it lists the settings (Socket Mode, themessage.channels/message.groupsevents, Bot Token scopes, for DMs the optionalmessage.imevent,im:historyscope and Messages tab, and for attached files the optionalfiles:readscope) and copies the part to add to its App Manifest. With Socket Mode on, that app's events go only to SockDock. If required scopes are missing, Connect to Slack names them. - Rules → Add Rule: pick the channel (channels the Slack app has been added to are listed; without the
channels:read/groups:readscopes, enter a channel ID or link) or DM, choose who can run it (everyone in the channel, or people you choose by name), choose which posts it reacts to (starting with, containing, a regular expression, or all; tick Only when mentioned to need a mention of the Slack app), and choose what runs — an AI agent (Claude Code or Codex) in a working folder, with instructions and what it may do, or a program. The list is grouped by channel and shows each rule's last run. Within a channel the rule higher up comes first; drag ⠿ to reorder. Open a rule for recent runs, thread links and Stop. - Post something like
<keyword> …in the channel.
The app runs the gateway while it is open — there is no separate service to install. Clicking the menu bar icon shows the connection, running and recent runs; There is one window: switch between Rules and Settings at the top. Settings (⌘,) has the Slack connection and who you are in Slack (see "Notifications by DM"), Open at login, notifications (Mac and Slack DM), the language (also used for the messages posted to Slack), MCP and Reset SockDock…, which removes the tokens, rules, run history and app settings and starts over from setup (the config file goes to the Trash; logs are kept). Open Config File opens the YAML in your editor for anything the form does not cover. A rule with a problem (e.g. a missing folder, or a rule above that always matches first) is shown in red and left out; the other rules keep running.
If a sockdock service install service is already running, the app shows its state and does not start its own gateway.
Who can run a rule
Anyone who can post in a channel can trigger its rules. To limit a rule to some people, list their Slack member IDs:
routes:
- name: deploy
channel: C0123456789
starts_with: deploy
allowed_users: [U0123ABCD, U0456EFGH]
handler: { type: command, cwd: ~/ops, command: ./deploy.sh }
- Posts and thread replies from anyone else are ignored: no 👀, no reply, and they never reach the handler. A rule further down the channel can still pick up their post.
- In the app, open the rule, set Who Can Run It to Chosen People and add people by name. Choosing by name needs the
users:readscope, which the bundled manifest includes. Without it, enter member IDs (in Slack, a profile's ⋮ menu → Copy member ID).users:readlets the app read the profiles of the workspace's members; SockDock uses it only for this list. - An agent rule that is open to everyone and may run commands or edit files shows a warning in the app.
Handlers
Every handler receives this JSON (on stdin for command handlers):
{
"route": "echo",
"turn": 1,
"channel": "C0123456789",
"thread_ts": "1762920000.000100",
"permalink": "https://example.slack.com/archives/C0123456789/p1762920000000100",
"groups": { "text": "hello" },
"messages": [{ "ts": "1762920000.000100", "user": "U0123", "text": "echo hello" }]
}
groups holds the values taken from the first message (see the table above) and is passed on every turn of the thread.
Attached files
Files attached to a post or a thread reply (screenshots, logs, PDFs, …) are handed over with it, so you can ask "look at this screenshot". A message with files gets a files list:
"messages": [{ "ts": "1762920000.000100", "user": "U0123", "text": "check this log",
"files": [
{ "name": "app.log", "mimetype": "text/plain", "size": 18233, "path": "/Users/me/Library/Caches/sockdock/files/812/app.log" },
{ "name": "build.zip", "mimetype": "application/zip", "size": 73400320, "skipped": "too_large" }
] }]
- The files are saved for this run only (in
~/Library/Caches/sockdock/files/, outside the rule's folder) and deleted when it ends. Copy them if you need them later. - A file that is not handed over has
skippedinstead ofpath:too_large(oversettings.max_file_mb, 20 MB by default),external(stored outside Slack, e.g. Google Drive),unsupported(Slack posts and canvases),no_scope(the Slack app lacksfiles:read) orfailed. The run goes ahead with the text and the other files; SockDock posts nothing about it, so the handler decides whether to mention it. - Only files of posts that start or continue a run are fetched. Posts from people a rule does not allow are never fetched.
- This needs the
files:readBot Token scope, which the bundled manifest includes. Without it, the rule's recent runs say the files were not passed on.files:readcan read files in the channels and DMs the Slack app is in; SockDock reads only the files of posts that run a rule. - File contents are untrusted input, just like the post text: a screenshot or a log can contain instructions aimed at the agent.
command
handler:
type: command
cwd: ~/my-handlers
command: ["uv", "run", "python", "bot.py"] # no shell is involved
env_file: .env # optional, relative to cwd
timeout_sec: 300
- stdout is posted to the thread (nothing is posted if it is empty).
- Environment:
SLACK_CHANNEL,SLACK_THREAD_TS,SOCKDOCK_ROUTE,SOCKDOCK_TURN, plusenv_file/env. Slack tokens are never passed: the reply is whatever the handler prints. - A non-zero exit or a timeout posts a short error; stderr goes to the log only.
claude
handler:
type: claude
cwd: ~/projects/my-project
prompt: prompts/slack.md # appended to the system prompt every turn
allowed_tools: ["Bash(make test *)", "WebSearch", "WebFetch"]
model: opus
timeout_sec: 600
- Runs
claude -p --output-format json --permission-mode dontAskwith yourallowed_tools; anything else that needs approval is denied. Read, Glob and Grep are available; MCP tools are off unlessallow_mcp: true. - Each thread keeps its session and resumes it on the next reply. If it cannot be resumed, a new conversation starts and the thread is told so.
- Messages that arrive while Claude is working are handed over together in the next turn.
- Attached files are listed in the prompt with their paths, and for that turn the agent may read their folder (
Read(//…/**)is added to the allowed tools). Claude Code's Read shows images and PDFs too. Files from earlier turns are gone, but what the agent read stays in the conversation. - Claude Code uses your own login. Because
--bareis not used, the project's.claude/settings.json,CLAUDE.mdand hooks apply too — take them into account when deciding what a route may do. - Set
settings.claude_commandto an absolute path: version-manager shims (mise, asdf, …) often fail when SockDock starts Claude Code. The menu bar app gives handlers your login shell'sPATH;sockdock service installrecords thePATHit was run with.
codex
handler:
type: codex
cwd: ~/projects/my-project
instructions: List at most three likely causes. # or prompt: a file
allow_web: true # web search (off unless set)
allow_edit: false # edit files in cwd (off unless set)
model: gpt-6-luna # optional
timeout_sec: 600
- Runs
codex exec --jsonand resumes the thread's conversation (codex exec resume) on every reply, like the claude handler. Sign in once withcodex login(ChatGPT or an API key). - Commands cannot be limited to a list. Codex always runs commands, inside its sandbox: no network, writes only in
cwdand only withallow_edit. In your home folder it can read onlycwd, the turn's attached files and the folders onPATH; outside your home folder (system tools, Homebrew) it can read.allowed_toolsis for Claude Code and is rejected here. If a rule should run only some commands, use Claude Code. - Your
~/.codex/config.toml(its MCP servers and plugins) is not loaded, and ChatGPT apps are off, unlessallow_mcp: true. The project'sAGENTS.mdapplies; its.codex/settings apply only if you trusted that folder in Codex. - Set
settings.codex_commandto an absolute path, as for Claude Code (the app fills it in when you save a Codex rule).
DMs and mentions
A rule can react to DMs sent to the Slack app instead of a channel's posts, and a channel rule can require a mention of the app:
routes:
- name: todo
channel: dm # DMs to the Slack app, from anyone allowed below
starts_with: todo
allowed_users: [U0123ABCD]
handler: { type: claude, cwd: ~/notes }
- name: review
channel: C0123456789
starts_with: review
mention_only: true # only "@SockDock review …"; plain "review …" does nothing
handler: { type: claude, cwd: ~/projects/web-app }
- DMs work like channel posts: a top-level DM starts a thread, SockDock replies in it, and replies in that thread continue the conversation. DM rules are tried from the top like a channel's.
- Without
allowed_users, anyone in the workspace can run a DM rule. In the app a new DM rule starts limited to you (see "Notifications by DM"). - A mention in the middle of a thread never starts a rule; only top-level posts do.
- DMs need the App Home Messages tab (with sending messages allowed), the
im:historyBot Token scope and themessage.imevent. The bundled manifest has them; the rule page and Settings say whenim:historyis missing.im:historyreads only DMs sent to the Slack app. Mentions need nothing new.
Notifications by DM
SockDock can also send its notices to you as Slack DMs, not only as Mac notifications. Register who you are in Slack once:
- In the app, Settings → Slack → Register Yourself (or
sockdock owner register). A six-digit code appears; it changes every 30 seconds. Copy copies it. - Send that code to the Slack app as a DM. If it matches, the sender is registered and gets "✅ You're registered."
Codes are accepted for 10 minutes after you start, and five wrong codes end it. If the wrong person got registered, press Remove and register again. Settings shows your name when the Slack app has users:read; without it, your member ID.
Settings → Notifications has a switch for the Mac and one for Slack DMs. By DM you get: Claude Code or Codex being signed out (once each, until it is signed in again) and rules changed through MCP. Turn on Also send failed runs to get a DM for every failed run too (there can be many). In the config these are settings.owner, settings.notify_dm and settings.notify_dm_failures.
Updates
SockDock checks GitHub for a newer release when it starts and once a day, and tells you once per version: a Mac notification and a Slack DM (each follows its switch in Settings → Notifications). While a newer version is out, the menu bar menu has Update to SockDock 0.2.0…: it shows the release notes in your language, then Update opens Terminal and runs brew upgrade --cask iwamatsu0430/tap/sockdock, which quits the app and opens it again when done. If a rule is running, the dialog says that updating stops it.
Turn the check off in Settings → General → Check for Updates (settings.check_updates: false). Only the request to GitHub leaves your Mac; tokens, settings and rules are not sent. Builds from source never check. Without the app, sockdock status shows a newer version.
Configuration reference
settings:
max_concurrency: 3 # handlers running at the same time (restart to change)
thread_ttl_days: 30 # how long a thread stays bound to its route
max_file_mb: 20 # larger attached files are not handed over
ack_reaction: eyes
claude_command: claude # string or list; per-route `command` overrides it
codex_command: codex # the same, for codex handlers
language: auto # canned replies posted to Slack: auto, en, ja
path: ["/opt/homebrew/bin"]
secrets_file: secrets.env
messages: # override canned replies; placeholders {route} {timeout_sec}
timeout: "Timed out after {timeout_sec}s."
owner: U0123ABCD # you, registered with a code (sockdock owner register)
notify_dm: true # notices by Slack DM to the owner
notify_dm_failures: false # also a DM for every failed run
check_updates: true # look for a newer SockDock once a day
${VAR}in a route is read from itsenv_file, then from the environment.- Unknown keys are rejected, so typos show up in
sockdock check. - Reload a changed config with
sockdock reload(orSIGHUP, or saving in the app).
CLI
| Command | |
|---|---|
sockdock run | Run the gateway in the foreground |
sockdock init / check / match | Create, validate and test the config (match dm "<text>" tries a DM; --mention a post that mentions the app) |
sockdock owner / owner register / owner clear | Show, register or remove who gets notices by DM |
sockdock status | Gateway status, and a newer version if one is out (exit code 1 if not running or not connected) |
sockdock reload | Re-read the config |
sockdock threads / turns / logs | Recent threads, handler runs and log lines |
sockdock pause <route> / resume <route> | Pause or resume a route |
sockdock auth set / status / delete | Manage tokens in the Keychain |
sockdock service install / uninstall / status | Background service for use without the menu bar app (launchd / systemd) |
sockdock manifest | Print the Slack app manifest |
sockdock mcp | Serve MCP over stdio (see "MCP" below) |
Files: data and the control socket are in ~/Library/Application Support/sockdock/, logs in ~/Library/Logs/sockdock/, attached files (only while a run uses them) in ~/Library/Caches/sockdock/files/.
MCP
While SockDock runs (the app or sockdock run), MCP clients such as Claude Code and Codex can control it — e.g. "add a rule that runs Claude Code in ~/app for posts in #ask".
The easiest way to register it is Settings → MCP in the app: pick your client and copy. To register by hand (<sockdock> is the CLI's absolute path; in the app, SockDock.app/Contents/MacOS/sockdock):
| Client | Register with |
|---|---|
| Claude Code | claude mcp add -s user sockdock -- <sockdock> mcp |
| Codex | codex mcp add sockdock -- <sockdock> mcp |
| Antigravity | agy mcp add sockdock <sockdock> mcp |
| VS Code | code --add-mcp '{"name":"sockdock","command":"<sockdock>","args":["mcp"]}' |
| Claude Desktop | in the app, Settings → MCP, choose Claude Desktop and press Add to Claude Desktop (it builds and opens the SockDock.mcpb extension) |
| Cursor / others | add "sockdock": {"command": "<sockdock>", "args": ["mcp"]} to mcpServers in its config file |
The tools show the status, rules, recent runs and channels, test which rule a post would hit, find people by name for who can run a rule, add, change, delete, reorder and turn rules on or off, and stop runs.
- A rule changed through MCP raises a notification on the Mac (even with notifications off), and a DM when notices by DM are on.
- MCP cannot register or remove the owner.
- Tokens and post texts are never passed to MCP.
sockdock mcprefuses to start inside a run started by SockDock (an agent answering a Slack post).
Development
mise tasks # list tasks
mise run ci # vet, tests, frontend type check
mise run gateway # build and run the gateway
mise run gui # build and open SockDock.app
mise run gui-preview # the GUI in a browser at http://localhost:8080 (no tray)
mise run preview # the same against a fake Slack, with sample rules; real data untouched
mise run preview (scripts/preview.sh) keeps its data in ~/.cache/sockdock-preview. PREVIEW_RESET=1 starts over, PREVIEW_NO_IM=1 plays a Slack app without im:history, PREVIEW_NO_UPDATE=1 hides the fake newer version (v0.2.0) it otherwise offers, and curl 'http://127.0.0.1:8766/dm?text=…' sends a DM from the fake person.
To keep development away from your real config, set SOCKDOCK_DATA_DIR and SOCKDOCK_CONFIG (see the [env] section of mise.toml).
Layout: cmd/sockdock (CLI), internal/ (gateway, handlers, control API, …), gui/ (Wails v3 + Svelte), examples/ (sample handlers), scripts/ (app bundling, also usable without mise).
License
https://github.com/iwamatsu0430/sock-dock-slack/releases/download/v0.2.1/SockDock-0.2.1.mcpb# mcpb: https://github.com/iwamatsu0430/sock-dock-slack/releases/download/v0.2.1/SockDock-0.2.1.mcpb