Connect Slack

A Gutternote workspace owner connects Slack once. Each project then picks its own channel.

1. Connect the workspace

Open a project’s Slack channel page. In the Slack workspace card, select Connect Slack and approve Gutternote in Slack. Every project in the workspace shares this connection.

Each connection link can be used once. If a link has expired, was already used, or you canceled approval, return to Gutternote and select Connect Slack again. Canceling keeps the existing connection and project choices.

Slack asks once, when you connect, for every permission Gutternote’s Slack features use, so nothing on the page asks again later. Before it sends you to Slack, the card lists them:

Post and update Gutternote’s own messages, including in public channels it hasn’t been invited to (chat:write, chat:write.public).
See channel names, so you can pick one. Private channels appear after you invite @Gutternote (channels:read, groups:read).
Read messages in public channels Gutternote is in. It imports only new replies in its own threads, never older messages (channels:history).
See members’ names and email addresses, so a reply shows under the right Gutternote account and a personal message reaches the right person (users:read, users:read.email).
Send direct messages to people who switch them on in their own settings (im:write).
Upload a note’s images to show them on its message and in its thread, and import images from replies (files:write, files:read).

With channel history, Slack sends Gutternote every new message in public channels it’s in. Gutternote keeps only new replies in its own threads and drops the rest without storing them. On a deployment that doesn’t import Slack replies, Connect leaves channels:history out.

Every feature is on by default: reply importing, image uploads and image imports included. Turn any of them off for a project on its Slack channel page. Personal DMs still start off for each person, who chooses them in their own settings.

Reconnect for updated permissions

A workspace connected before Gutternote asked for everything at once, or one whose Slack admin approved only posting, shows Reconnect Slack to grant its updated permissions on the Slack workspace card. A workspace owner selects Reconnect Slack and approves the full list once. Until then, the features that need the missing permissions stay off, and their settings say so.

2. Choose a channel

In Slack, invite the bot to the channel:
```
/invite @Gutternote
```
On the project’s Slack channel page, type part of the channel’s name in Channel and pick it from the matches. A leading # is optional, and a space matches the - in a name.
Turn on Post this project’s notes to Slack.
Select Save.

To send notes on pull request previews to a different channel, set Pull request previews (optional) the same way. Left empty, they go to Channel.

Gutternote lists every channel it can see, even in a workspace with thousands of channels. Most workspaces list in a few seconds; a very large one can take up to a minute, and you can search what has arrived while the rest loads.

If the channel you want isn’t listed, type /invite @Gutternote in it, then select Refresh channels under the fields. If the list was refreshed moments ago, the page says how long to wait before trying again. The page also refreshes the list when you come back to it after a minute or more. A saved channel stays selected even when it is absent from the list.

3. Choose what gets posted

Under What posts, turn each event on or off:

New notes
Replies
Agent updates
Resolved and reopened

What appears in Slack

A note’s card starts with a line saying what it is and which project it belongs to and, while the note is open, what to do: Reply in this thread to answer it in Gutternote, or Open the note to reply when reply importing is off. A note on a pull request preview is titled New comment on PR #N with the pull request’s number, linked to the pull request on GitHub when the project is connected to a repository. Replies start with who replied and don’t name the project.

Below that line, a colored bar holds the note itself — its page, who left it and its words — and its buttons. ✅ Resolve resolves the note, and anyone in your workspace who can see the message can use it. Gutternote records them by their Slack name, for example “sam on Slack”. Once the note is resolved, the button becomes 🔄 Reopen. An archived note has neither. 📌 Open opens the pin on its page; Open in Gutternote opens the project. No button starts an agent.

The bar’s color follows the note’s state: yellow while it is open or reopened, green once resolved, blue for an agent’s reply, and gray for archived notes. The state is always written out as well, so nothing depends on the color. A person’s reply has no bar, and neither does a deleted note’s card: it becomes a plain Original note deleted line. Visual cues help you scan: ✅ beside Resolved, 📝 for a new note, 💬 for a person’s reply, and 🤖 beside the name of an agent, on its replies and on anything it resolved or reopened.

For projects whose comments are stored in Gutternote, a note’s card quotes the start of its own words, about 300 characters, cut at a word, with the element it was pinned to underneath. What a reviewer wrote can’t mention @channel or anyone else, link anywhere or change the card’s layout, though Slack’s own formatting, such as *bold*, still applies to it. Projects that store comments outside Gutternote never send their words, the element or a screenshot to Slack: their cards say who left a note and where, with links.

Every card is sent with a text version that has the same information, which Slack uses for notifications and assistive readers. If Slack can’t show a card, Gutternote tries the same card without its images, then the text version.

Each note starts its own message, on a site, a branch or a pull request preview. Replies and agent updates go in its thread. A branch preview’s card also names the branch. A note’s message stays in the channel it was first posted to, even if you change the channels later.

Images on a note’s message

Where a project shares images with Slack (see Share screenshots and images), a note with a screenshot, or with an image on its opening comment, has that image attached to its message, as on a Slack message with a file attached. If Slack refuses the image, the note is posted without it rather than not at all. A second image on the opening comment, and images on replies, go into the note’s thread.

Removing the image from the opening comment, or deleting the comment, deletes Gutternote’s copy in Slack, which takes it off the message.

Uploading images is separate from text posting and is on by default where comments are stored in Gutternote and image storage is available. To turn it off, untick Upload a note’s images to Slack under Slack channel → Screenshots and images, and Save. Posting and the relevant event switch must also be on for uploads to happen.

With uploads on, a note’s screenshot and the images on its opening comment appear on the note’s own message (see Images on a note’s message), and images on replies appear as files in the note’s Slack thread, a pull request note’s included. Gutternote prefers an available selected-element crop over the full capture and avoids sending both. If the selected crop can’t be shared, the pin still opens the source; Gutternote doesn’t substitute the larger full capture after a crop failure. Supported formats and sizes follow the image upload contract; this does not add document, PDF or video uploads. Older images aren’t backfilled when sharing, posting or permissions are turned on.

If an image cannot be shared, the card and its pin link remain available. The settings page reports uploads or removals needing attention. An uncertain upload is held rather than creating another copy; contact us before retrying it.

Turning uploads off stops new ones. Removing a source image or note queues removal of Gutternote’s Slack copy where the app still has access. Revocation, disconnection or an ownership refusal can prevent cleanup; the page does not report successful removal until it is confirmed. Slack caches, downloads and another person’s copies may remain. Source objects in Gutternote’s bucket retain their existing storage lifecycle.

Projects storing comment bodies elsewhere cannot export their image bytes. Uploads never make an attachment URL public, import Slack files or start an agent. Personal DMs remain a separate preference and deployment gate.

Bring Slack replies into Gutternote

Replies from Slack come into Gutternote by default. On each project’s Slack channel page, Bring replies from Slack into Gutternote starts ticked once the project’s channel is a public one with @Gutternote in it. Until it is, the page says what to change. Select Save to start importing. Only a workspace owner can change the setting, and a project saved with it off stays off, through reconnecting.

A workspace without the reply permissions needs one reconnect first; until then the setting says so. Reconnecting on its own imports nothing: each project still needs the setting saved.

Then:

Only new replies in public channels where the bot is a member come across. Older messages aren’t backfilled. Private channels and Slack Connect are not supported. Image importing below includes its source edit/removal path.
A reply in a note’s own thread goes to that note.
A reply you also send to the channel (Also send to #channel) comes across like any other reply in its thread.
If you edit a reply while it’s still waiting to come across, the edited reply is the one that comes across.
Files stay in Slack unless the owner separately enables supported image importing below. Unsupported files stay in Slack, with a source link on the imported reply that says how many files the message has. Deleting a file in Slack takes it off that count. A file after the first ten lags; it comes off later, when files are removed from the message or it’s edited with image importing on.
A reply shows under the sender’s Gutternote account only if they are a workspace member and their Slack email matches both their Gutternote email and their Google sign-in. Otherwise it can appear as a separate Slack-domain identity when the project allows Google, named domains only, Slack marks the sender’s email confirmed, and that email is on the project’s allowlist. This identity is not a Gutternote account or member and cannot start agent work. Under Anyone, other eligible senders appear as guests; stricter sign-in rules drop replies that match neither identity. Projects using your own identity provider never import Slack replies.
When a reply is stored successfully or refused, Gutternote may send the author a fixed private status in the thread. During a retry it may say the reply is still being checked. These notices are best-effort; the project’s reply receipt is the record of whether the reply was saved.
Projects that store comments outside Gutternote can’t import replies. For a mapped external-store thread, Gutternote may send a fixed private notice explaining that Slack replies aren’t imported and directing the author to reply on the pin in Gutternote. It never copies the Slack reply into that project’s external store.

If your Gutternote account email and Google sign-in email differ, changing your Slack email alone won’t restore replies under your Gutternote name. Open Personal settings → Sign-in & security → Change Google account and link the Google account with your current Gutternote email. Your Slack email must match that address too. Until they match, the guest or sign-in rule above still applies; reconnecting Slack does not change your identity.

Import images from Slack

Image importing is on by default, separate from outbound image sharing. It requires comments stored in Gutternote, configured image storage, and reply importing on a supported public Slack channel. To turn it off, untick Import supported images from Slack under Slack channel → Replies from Slack, and Save. Turning reply importing off turns it off too.

New eligible replies can include supported image attachments or only images. The images appear on the same Gutternote pin using its normal attachment viewer. Formats and sizes follow the image upload contract. This does not import documents, PDFs, video, private-channel messages or Slack Connect files. Reconnecting or enabling imports does not backfill older files.

The reply is saved before its images finish copying. If a file is pending, unsupported or cannot be copied, the reply retains a link to its Slack source; accompanying text is preserved. The settings page reports image imports or removals needing attention. A failed copy is not displayed as an imported image.

With image importing on, source edits update the same imported reply and its image references. An edit imports only the images it adds. An image already on the Slack message that wasn’t imported stays in Slack, so editing a reply never backfills images posted before imports were on. Editing a reply’s words in Slack keeps the imported reply’s file count, brought up to date, and its Slack source link. A link preview appearing or an image finishing processing in Slack isn’t an edit, so it leaves the reply alone and doesn’t send it to your agent again. Editing a pull-request note label cannot move that reply to another pin. Removing a source image or deleting the Slack message removes it from the imported reply; delayed events cannot recreate a deleted source. Source removal remains available after imports are turned off, the project switches to another channel, or its workspace connection is renewed. A conflicting local edit or deletion is preserved rather than overwritten by an old Slack event.

Turning reply importing off also turns image importing off. Gutternote never deletes another person’s original Slack upload. Removing an attachment reference and physically cleaning up an unreferenced private stored copy are separate steps; storage cleanup follows the deployment’s retention policy. Slack caches, downloaded files and copies someone else made may remain. Image importing does not start an agent, echo the file back into Slack, or enable personal DMs.

Personal direct messages

On deployments where personal DMs are available, open Personal settings → Notifications → Slack direct messages. Each workspace has its own choice; DMs start off and changing your choice never opts in anyone else.

If the workspace was connected without the DM permissions, a workspace owner reconnects it once. Granting them does not turn on anyone’s DMs.
Select Link my Slack account for the workspace. Gutternote matches only your verified sign-in email against that workspace’s Slack connection and shows the matched identity. Bots, restricted guests and external or deactivated accounts cannot be linked.
Turn on DM me when someone else replies to my notes.

You receive a DM when someone replies to your own original note or a built-in agent posts its final result. Your own replies, agent placeholders and human mentions never trigger a DM. This choice is independent of Email me about replies and channel activity preferences. The project must still have Slack enabled.

Notes in customer-owned body stores receive a link-only notification. Older external notes without a recorded original author do not receive DMs. Connected MCP agent result publication remains outside this release.

Turning your choice off stops queued DMs that have not begun sending. Losing workspace or project access, disconnecting Slack or changing the installation also prevents delivery under the old link. Link and opt in again when asked. Messages already delivered in Slack stay there.

Disconnect

Disconnecting stops posting, image uploads, personal DMs and reply importing for every project in the workspace. Saved channel choices stay. Messages and images already in Slack may stay; remote cleanup needs a valid app connection.

When the connection stops

If Slack reports an uninstall or bot-token revocation, Gutternote checks the current connection before stopping it. A delayed report must not stop a healthy replacement connection. When the current connection is confirmed unavailable, the Slack workspace card shows the problem. A workspace owner can select Reconnect Slack.

Your project channel choices and saved switches stay. Reconnecting does not turn an off switch on. Reply importing may need its extra permissions approved again.

When a reply may be missing

Slack can limit event delivery. If it reports this for your workspace, projects with reply importing enabled show a notice beside Replies from Slack, with Slack’s reported time. That time is a rounded minute, not a list of missing messages or proof the limit is still active. Outbound posting can continue.

Gutternote cannot recover these replies automatically. To add a missing reply, post it again as a new message in the original Slack thread. Editing the old message does not import it.

A workspace owner can select Dismiss notice after reviewing it. This hides the shared notice on that workspace’s project pages; it does not recover any messages. A later reply or reconnect does not dismiss it. If Slack reports a gap for a later minute, the notice comes back. A delayed older report does not replace a newer notice.