Repository avatar
Communication
v0.2.1
active

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.

Website · 日本語

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.

Posts in Slack channels and DMs reach SockDock on your local Mac over one Socket Mode connection. SockDock runs Claude Code or a program for the rule each post matches.

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:

  1. Click Done (not Move to Trash).
  2. Open System Settings → Privacy & Security, scroll down and click Open Anyway.
  3. 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
  1. Open https://api.slack.com/apps?new_app=1, choose From a manifest, and paste the manifest.
  2. Basic Information → App-Level Tokens: generate a token with the connections:write scope (xapp-…).
  3. Install App: install it to your workspace and copy the Bot User OAuth Token (xoxb-…).
  4. 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).

KeyPosts it runs ongroups
starts_with: echoPosts starting with the keywordtext: what follows the keyword
contains: reviewPosts containing the keywordtext: the whole post
match: '^deploy (?P<env>\w+)$'Posts matching the regular expression (RE2)the named groups
all_posts: trueEvery posttext: 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):

  1. 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, the message.channels/message.groups events, Bot Token scopes, for DMs the optional message.im event, im:history scope and Messages tab, and for attached files the optional files:read scope) 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.
  2. Rules → Add Rule: pick the channel (channels the Slack app has been added to are listed; without the channels:read/groups:read scopes, 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.
  3. 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:read scope, which the bundled manifest includes. Without it, enter member IDs (in Slack, a profile's ⋮ menu → Copy member ID). users:read lets 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 skipped instead of path: too_large (over settings.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 lacks files:read) or failed. 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:read Bot Token scope, which the bundled manifest includes. Without it, the rule's recent runs say the files were not passed on. files:read can 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, plus env_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 dontAsk with your allowed_tools; anything else that needs approval is denied. Read, Glob and Grep are available; MCP tools are off unless allow_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 --bare is not used, the project's .claude/settings.json, CLAUDE.md and hooks apply too — take them into account when deciding what a route may do.
  • Set settings.claude_command to an absolute path: version-manager shims (mise, asdf, …) often fail when SockDock starts Claude Code. The menu bar app gives handlers your login shell's PATH; sockdock service install records the PATH it 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 --json and resumes the thread's conversation (codex exec resume) on every reply, like the claude handler. Sign in once with codex 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 cwd and only with allow_edit. In your home folder it can read only cwd, the turn's attached files and the folders on PATH; outside your home folder (system tools, Homebrew) it can read. allowed_tools is 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, unless allow_mcp: true. The project's AGENTS.md applies; its .codex/ settings apply only if you trusted that folder in Codex.
  • Set settings.codex_command to 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:history Bot Token scope and the message.im event. The bundled manifest has them; the rule page and Settings say when im:history is missing. im:history reads 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:

  1. In the app, Settings → Slack → Register Yourself (or sockdock owner register). A six-digit code appears; it changes every 30 seconds. Copy copies it.
  2. 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 its env_file, then from the environment.
  • Unknown keys are rejected, so typos show up in sockdock check.
  • Reload a changed config with sockdock reload (or SIGHUP, or saving in the app).

CLI

Command
sockdock runRun the gateway in the foreground
sockdock init / check / matchCreate, validate and test the config (match dm "<text>" tries a DM; --mention a post that mentions the app)
sockdock owner / owner register / owner clearShow, register or remove who gets notices by DM
sockdock statusGateway status, and a newer version if one is out (exit code 1 if not running or not connected)
sockdock reloadRe-read the config
sockdock threads / turns / logsRecent threads, handler runs and log lines
sockdock pause <route> / resume <route>Pause or resume a route
sockdock auth set / status / deleteManage tokens in the Keychain
sockdock service install / uninstall / statusBackground service for use without the menu bar app (launchd / systemd)
sockdock manifestPrint the Slack app manifest
sockdock mcpServe 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):

ClientRegister with
Claude Codeclaude mcp add -s user sockdock -- <sockdock> mcp
Codexcodex mcp add sockdock -- <sockdock> mcp
Antigravityagy mcp add sockdock <sockdock> mcp
VS Codecode --add-mcp '{"name":"sockdock","command":"<sockdock>","args":["mcp"]}'
Claude Desktopin the app, Settings → MCP, choose Claude Desktop and press Add to Claude Desktop (it builds and opens the SockDock.mcpb extension)
Cursor / othersadd "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 mcp refuses 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

MIT

MCPB
https://github.com/iwamatsu0430/sock-dock-slack/releases/download/v0.2.1/SockDock-0.2.1.mcpb
Install Command
# mcpb: https://github.com/iwamatsu0430/sock-dock-slack/releases/download/v0.2.1/SockDock-0.2.1.mcpb