Inbox and Slack

The inbox collects work that arrives from outside: today, mainly Slack messages that mention you. Each item waits until you read it. When you accept it, spekterm opens a claude session in the folder you confirm, with the message as context and a first prompt typed in — but not sent. You press Enter.

Open the inbox with Handoffs on the activity bar (the column at the far left). The entry shows how many items are waiting.

Reviewing an item

Each item shows where it came from, who wrote it, when it happened, and its full text — before anything is opened. The text is shown as plain text, exactly as the agent will receive it.

• Opens in shows the folder the item will open in. spekterm preselects one using your routing rules; you can pick another. Nothing opens until a folder is confirmed.
• Accept opens a claude session in that folder. The item’s text is handed to the agent as context, and a prompt that points at it is typed into the agent’s input. Read it, change it if you like, and press Enter to send.
• Dismiss removes the item without opening anything.

Once accepted, an item shows as Already opened until you Clear from inbox, so you can still reread what you accepted.

Message text written by someone else is never sent to an agent on its own. You review it first, and the first prompt waits for your Enter.

Notifications

When new items arrive, spekterm shows a desktop notification. Several arrivals at once are merged into one. Clicking the notification brings spekterm to the front with the inbox open.

Routing rules

The Routing rules tab decides which folder is preselected for an item.

• Rules are checked from top to bottom; the first one that matches wins. Each rule picks a field (Match on), a text it must Contain, and the folder to Open in. Reorder rules with the arrow buttons.
• Default folder is used when no rule matches. Set one — otherwise items arrive with no folder chosen, and you pick one each time.
• Some fields, such as the title and the message text, are written by whoever sent the item. Rules on those fields are marked, because a sender can word a message to steer where it opens.

If a rule points at a folder that is no longer in your workspace, the item says so instead of quietly opening somewhere else.

Connecting Slack

The Slack tab connects your Slack account. spekterm then finds messages that mention you — the person the token belongs to — and turns each one into an inbox item, with the thread up to that message as context. A very long thread is shortened, and the item says so.

You need a Slack app in your workspace with a user token. Give the token these user token scopes:

channels:history  groups:history  im:history  mpim:history
channels:read     groups:read     im:read     mpim:read
users:read

The *:history scopes let spekterm read messages; the *:read scopes let it list the conversations you are in; users:read turns user IDs into names. After changing scopes, reinstall the app and copy the token again. Paste it under User token and save. Your identity is read from the token — there is nothing else to fill in.

When mentions arrive

spekterm checks for new mentions when it starts, every five minutes, and right after you save a token. Look-back window sets how far back the startup check searches: Slack does not replay what happened while spekterm was closed, so mentions older than the window are missed.

For mentions within seconds, also add an app-level token: enable Socket Mode for your Slack app and create an app-level token for it. Live updates then shows whether the live connection is on. If it drops, spekterm falls back to the periodic check.

Status

The tab always says what state the connection is in: not set up, working with nothing new, how many mentions arrived on the last check, Slack asking to slow down, or credentials that are invalid or missing scopes. A broken connection never looks like “nobody mentioned you”.

Your tokens

Tokens are stored in ~/.config/Spekterm with access limited to your user. They are sent only to Slack (or to the endpoint you set under API endpoint — only change it if you know why), and never reach your terminals or your agents. See Data and network.

Rejected deliveries

An item that cannot be accepted into the inbox — unreadable, too long to review, or naming a repository that is not in your workspace — is not dropped silently. The inbox lists each rejection with its reason until you clear it, including after a restart.