Skip to main content
Glama

laptop-bridge

Formerly slack-to-laptop.

One long-lived local process that turns a message into work on this laptop, and reports back where the message came from. Two front doors, one back room:

  • Slack: @mention the bot (Socket Mode) → a worktree job, streamed back into the thread.

  • Linear: delegate an issue to the agent, @mention it, move an issue to a trigger status, or start a project → a lane (worktree + Claude session) that answers in Linear's agent sessions and keeps the project's issues up to date.

  • Back room: a local HTTP MCP server the jobs call to report progress, a registry that routes follow-ups into the running Claude session, and a SwiftBar menubar status.

The job never holds Slack or Linear credentials. It only knows a correlation token passed in its prompt (threadTs for Slack, a lane key and session id for Linear); this process maps it to the real thread and owns the tokens. State is snapshotted under ~/.cache/slack-to-laptop/, so restarting the bridge doesn't interrupt running jobs.

How it's built / build your own: RECIPE.md.

Slack app (one-time)

  1. https://api.slack.com/apps → Create New App → From scratch.

  2. Agents & AI Apps feature → toggle ON (grants assistant:write, required for streams + setStatus).

  3. Socket Mode → ON → create app-level token with scope connections:write → that's appToken (xapp-…).

  4. OAuth & Permissions → bot scopes: app_mentions:read, chat:write, assistant:write.

  5. Event Subscriptions → subscribe to bot event app_mention.

  6. Install to workspace → botToken (xoxb-…). Invite the bot to your channel: /invite @YourApp.

Note: Slack docs say setStatus is migrating from assistant:write to chat:write — both scopes above cover either.

Related MCP server: Slack Note Capture MCP Server

Run

mkdir -p ~/.config/slack-trigger
cp config.example.json ~/.config/slack-trigger/config.json
# fill botToken + appToken
bun run server.ts

allowedUserIds (Slack user IDs): when non-empty, only those users can trigger jobs — anyone else gets a threaded "only can trigger me" reply. Empty = anyone in the channel.

With jobCommand: null, mentioning the bot runs a smoke demo: instant thinking checklist, two task cards ticking, "hi", stream closed. That validates the whole Slack side before wiring any jobs.

Wire real jobs

Set jobCommand in the config — a zsh command run per mention with env:

var

value

SLACK_THREAD_TS

correlation token — pass to every MCP tool call

SLACK_CHANNEL

channel id

SLACK_PROMPT

mention text, bot mention stripped

SLACK_EVENT_TS

unique per mention — use for the worktree name

SLACK_MCP_URL

http://127.0.0.1:8365/mcp

Example: "jobCommand": "/Users/you/projects/laptop-bridge/scripts/launch-job.zsh" — see scripts/launch-job.zsh (machine-specific: Orca + repo hardcoded). It spawns a worktree Claude with prompt /slack-ta [threadTs:$SLACK_THREAD_TS] $SLACK_PROMPT: the token travels inside the prompt, since the job's Claude only sees what the skill receives (see "Job-side skills" below).

Connect the worktree's Claude to the MCP (once, user scope):

claude mcp add --transport http --scope user laptop http://127.0.0.1:8365/mcp

MCP tools

All take threadTs (from SLACK_THREAD_TS):

  • register_job({threadTs, cwd, paneId?, pid?, branch?}) — call once at boot; where the session lives, for follow-up routing (paneId = $ORCA_TERMINAL_HANDLE, or $TMUX_PANE on the tmux fallback)

  • thinking_step({threadTs, title, status, id?, details?}) — checklist step; status ∈ pending|in_progress|complete|error; same id/title updates the step

  • append_text({threadTs, markdown}) — prose in the progress message (important mid-course findings only)

  • set_status({threadTs, text}) — grey "is …" line; "" clears

  • finish({threadTs, markdown?}) — settle the progress message + post markdown as its own final-report reply (the user's one notification). Call exactly once, last (again after each follow-up).

Follow-ups

Mentioning the bot again in a job's thread does NOT spawn a second job: the bridge looks the thread up in ~/.cache/slack-to-laptop/jobs.json (written by register_job, survives finish for 7 days), verifies the session's terminal still sits in the job's worktree (a terminal id alone is not a handle — tmux recycles pane ids, Orca's handles go stale on an app restart — so cwd is ground truth), and types [slack follow-up threadTs:…] <text> into that Claude session — mid-work it's a steering message, after finish a new turn with full context. A stream is reopened first if needed ("Reconnecting to session…"). If the terminal is gone, it falls back to spawning a fresh job with a note. Only the typing is terminal-specific (src/inject.ts); finding the session is registration-based and generic.

Terminals (Orca + tmux)

Jobs run as Orca worktrees: orca worktree create gives each job its own checkout with Claude in the first terminal, and orca terminal send types follow-ups into it. tmux panes are still listed, so sessions started before the move stay reachable; no tmux server just means no tmux panes.

Two gotchas, both measured:

  • Use the CLI inside the app bundle (/Applications/Orca.app/Contents/Resources/bin/orca). The /usr/local/bin/orca symlink is root-owned mode 0700 and the CLI can't resolve Orca.app through it.

  • A repo with setupAgentStartupPolicy: wait-for-setup drops --prompt (launch.prompt.outcome is "not-delivered"): Claude starts on an empty input once setup ends. The Linear launcher (src/linear/launch.ts) waits for the prompt line and types the prompt itself, once.

Linear

Optional: everything below is off unless the config has a linear block.

The model. A Linear project is a lane: one worktree, one Claude session, and every issue of that project is routed to it — issues are the lane's own tracking, not separate jobs. An issue without a project gets its own lane.

What starts work

In Linear

In the bridge

Delegate an issue to the agent, or @mention it

New agent session → the issue's lane (created if needed)

Reply in an agent session

Typed into the lane's terminal as [linear follow-up session:…]

Move an issue into the trigger status (triggerStatus)

The bridge opens an agent session on the issue, then as above

Move a project to a started status

The project's lane is launched with the project as its brief

Messages that arrive while a lane is still booting are held and typed in when it registers. Only a human's change triggers work: the lane writes to Linear as the app, and events whose actor is not a user are ignored. At most maxLanes lanes with a live session run at once.

Setup (one-time)

  1. Linear webhooks are plain HTTPS POSTs, so the laptop needs a public URL. Tailscale Funnel, exposing that one path only: tailscale funnel --bg --set-path /linear http://127.0.0.1:8365/linear

  2. Linear → Settings → API → OAuth applications → New. Callback URL <publicUrl>/linear/oauth/callback, webhook URL <publicUrl>/linear/webhook. Events: Agent session events, Inbox notifications, Permission changes, plus Issues and Projects for the status triggers.

  3. Add to the config:

    "linear": {
      "clientId": "…", "clientSecret": "…", "webhookSecret": "…",
      "publicUrl": "https://<machine>.<tailnet>.ts.net",
      "triggerStatus": "Waiting for agent",
      "teamRepos": { "RBD": "/Users/you/projects/booker" },
      "projectRepos": { "Website": "/Users/you/projects/site" },
      "maxLanes": 3,
      "allowedUserIds": ["<your Linear user id>"]
    }

    allowedUserIds empty = any member of the workspace can start work.

    projectRepos (by project name) wins over teamRepos (by team key); an issue with no mapping is refused with a message in its session.

  4. Start the bridge, open http://127.0.0.1:8365/install/linear on the laptop and authorize the app for the teams it should see. The token (24h, refreshed automatically) is stored in ~/.config/slack-trigger/linear-token.json.

  5. Add the trigger status to each team's workflow by hand: an agent app is not allowed to edit workflows.

Security. Only /linear/* is reachable from outside. The webhook checks the Linear-Signature HMAC over the raw body, rejects timestamps older than a minute and drops redelivered ids; the OAuth callback only accepts a state this process issued. /mcp, /install/linear and /open/* are localhost only, and refuse any request whose Host is not a local name (a web page reaching 127.0.0.1 through DNS rebinding carries its own). Events signed for another workspace than the installed one are ignored. Text coming from Linear is typed only into a terminal Orca reports as running Claude, on one line, with control bytes removed and look-alike bridge tags defused.

MCP tools for the lane (same /mcp endpoint)

  • linear_register({lane, cwd, paneId?, branch?}) — call once at boot: routes follow-ups to this session, flushes held messages, attaches the "Open in Orca" link to the lane's sessions and project.

  • linear_activity({session, type, body | action…}) — post on an agent session: thought, action, elicitation (ask the user and wait), response, error.

  • linear_plan({session, items}) — the session's checklist (full list each time).

  • linear_graphql({query, variables?}) — anything else, as the app: read the project, create and move issues, post project updates.

  • linear_issue_search({query, team?}) / linear_issue_create({team, title, description?, labels?, project?, state?, priority?}) — file a follow-up or a papercut in one call; labels, project and status go by name. The trigger status is refused.

  • linear_adopt({project, cwd, paneId?, branch?}) — attach a worktree that was NOT started from Linear to a project, so the project's messages reach it.

A session without the MCP server connected can call the same tools through the running bridge: bun scripts/linear.ts <tool> '<json args>' (no arguments lists them). The script never touches the Linear token.

Open in Orca. GET /open/<lane> runs orca worktree activate on the lane's worktree. The link is attached in Linear as http://127.0.0.1:8365/open/<lane>, so it only does something on the laptop itself.

The job-side skill is linear-ta (the Linear twin of slack-ta, see below). Raw events are appended to ~/.cache/slack-to-laptop/linear-events.jsonl.

A job that dies without finish gets swept: streams idle > staleStreamMinutes are stopped and cleared.

Why each job gets ONE progress message (stream, then chat.update edits after ~3.5 min) and the Slack API quirks behind it: see RECIPE.md.

Job-side skills

Don't make each job improvise the protocol: the two skills in skills/ own it. slack-ta streams a Slack job (/slack-ta [threadTs:…] <task>), linear-ta runs a Linear lane (/linear-ta [lane:…] …). Install them with

npx skills add ArnaudRinquin/laptop-bridge --global

They are mine, so adapt them: slack-ta hands the task to a private /go pipeline (replace that step with your own workflow), and linear-ta names my workspace and team. What is worth keeping: pass the correlation token to every laptop MCP call, report at real milestones only, and always close the request (finish, or a response / error activity), also on failure. If the token is missing, do the work and skip the reporting; if a call errors with "no live stream", the stream was swept: continue the work, stop streaming.

GET /healthz lists active streams.

How it's built

Architecture, build-your-own steps, how the Linear front door was added, and the measured Slack / Linear / Orca / SwiftBar gotchas live in RECIPE.md.

SwiftBar

cp swiftbar/laptop-bridge.sh ~/Library/Application\ Support/SwiftBar/Plugins/  # or your plugin dir
chmod +x .../laptop-bridge.sh

Streamable plugin: SwiftBar owns the process lifecycle; menubar shows 🛰️ + active stream count. Don't also run bun run server.ts manually (port collision). Test from a terminal first: ./swiftbar/laptop-bridge.sh — you should see blocks starting with ~~~. Logs: ~/.cache/slack-to-laptop/server.log (written by the server itself — NEVER add a stderr redirect to the plugin script: closing SwiftBar's stderr pipe makes it spin at 100%+ CPU).

SwiftBar does NOT respawn the process if it dies. To restart the bridge: open -g "swiftbar://refreshplugin?name=laptop-bridge" (or SwiftBar menu → plugin → Refresh). If the 🛰️ icon is missing but the process runs, check defaults read com.ameba.SwiftBar for "NSStatusItem VisibleCC laptop-bridge.sh" = 0 and write it back to -bool true.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers