agent-slack 0.2.14 → 0.4.0

package/README.md

@@ -7,17 +7,9 @@ Guiding principle:
 - **token-efficient output by default** (compact JSON, minimal duplication, and empty/null fields pruned) so LLMs can consume results cheaply.
 - **zero-config auth** -- Auth just works if you have Slack Desktop (with fallbacks available). No Python dependency.
 
-## At a glance
-
-- **Read**: fetch a message, browse channel history, list full threads
-- **Search**: messages + files (with filters)
-- **Artifacts**: auto-download snippets/images/files to local paths for agents
-- **Write**: reply in thread, add reactions
-- **Canvas**: fetch Slack canvases as Markdown
+## Getting started
 
-## Installation
-
-Recommended (Bun install script):
+Install via Bun (recommended):
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/stablyai/agent-slack/master/install.sh | sh
@@ -29,6 +21,15 @@ OR npm global install (requires Node >= 22.5):
 npm i -g agent-slack
 ```
 
+## At a glance
+
+- **Read**: fetch a message, browse channel history, list full threads
+- **Search**: messages + files (with filters)
+- **Artifacts**: auto-download snippets/images/files to local paths for agents
+- **Write**: reply, edit/delete messages, add reactions
+- **Channels**: create channels and invite users by id/handle/email
+- **Canvas**: fetch Slack canvases as Markdown
+
 ## Agent skill
 
 This repo ships an agent skill at `skills/agent-slack/` compatible with Claude Code, Codex, Cursor, etc
@@ -60,9 +61,15 @@ agent-slack
 │   ├── get   <target>             # fetch 1 message (+ thread meta )
 │   ├── list  <target>             # fetch thread or recent channel messages
 │   ├── send  <target> <text>      # send / reply (does the right thing)
+│   ├── draft <target> [text]      # open Slack-like editor in browser
+│   ├── edit  <target> <text>      # edit a message
+│   ├── delete <target>            # delete a message
 │   └── react
 │       ├── add    <target> <emoji>
 │       └── remove <target> <emoji>
+├── channel
+│   ├── new                         # create channel
+│   └── invite                      # invite users to channel
 ├── user
 │   ├── list
 │   └── get <user>
@@ -127,10 +134,12 @@ agent-slack message get "#general" --ts "1770165109.628379"
 agent-slack message list "#general" --thread-ts "1770165109.000001"
 ```
 
-If you have multiple workspaces configured and you use a channel **name** (`#channel` / `channel`), you must pass `--workspace` (or set `SLACK_WORKSPACE_URL`):
+If you have multiple workspaces configured and you use a channel **name** (`#channel` / `channel`), you must pass `--workspace` (or set `SLACK_WORKSPACE_URL`).
+`--workspace` accepts a full URL or a unique substring selector:
 
 ```bash
 agent-slack message get "#general" --workspace "https://stablygroup.slack.com" --ts "1770165109.628379"
+agent-slack message get "#general" --workspace "stablygroup" --ts "1770165109.628379"
 ```
 
 ## Examples
@@ -149,6 +158,12 @@ agent-slack message list "https://workspace.slack.com/archives/C123/p17000000000
 
 # Recent channel messages (browse channel history)
 agent-slack message list "#general" --limit 20
+
+# Recent channel messages that are marked with :eyes:
+agent-slack message list "#general" --with-reaction eyes --oldest "1770165109.000000" --limit 20
+
+# Recent channel messages that do not have :dart:
+agent-slack message list "#general" --without-reaction dart --oldest "1770165109.000000" --limit 20
 ```
 
 Optional:
@@ -158,6 +173,65 @@ Optional:
 agent-slack message get "https://workspace.slack.com/archives/C123/p1700000000000000" --include-reactions
 ```
 
+### Draft a message (browser editor)
+
+Opens a Slack-like WYSIWYG editor in your browser for composing messages with full formatting support (bold, italic, strikethrough, links, lists, quotes, code, code blocks).
+
+```bash
+# Open editor for a channel
+agent-slack message draft "#general"
+
+# Open editor with initial text
+agent-slack message draft "#general" "Here's my update"
+
+# Reply in a thread
+agent-slack message draft "https://workspace.slack.com/archives/C123/p1700000000000000"
+```
+
+After sending, the editor shows a "View in Slack" link to the posted message.
+
+### Reply, edit, delete, and react
+
+```bash
+agent-slack message send "https://workspace.slack.com/archives/C123/p1700000000000000" "I can take this."
+agent-slack message edit "https://workspace.slack.com/archives/C123/p1700000000000000" "I can take this today."
+agent-slack message delete "https://workspace.slack.com/archives/C123/p1700000000000000"
+agent-slack message react add "https://workspace.slack.com/archives/C123/p1700000000000000" "eyes"
+agent-slack message react remove "https://workspace.slack.com/archives/C123/p1700000000000000" "eyes"
+```
+
+Channel mode requires `--ts`:
+
+```bash
+agent-slack message edit "#general" "Updated text" --workspace "myteam" --ts "1770165109.628379"
+agent-slack message delete "#general" --workspace "myteam" --ts "1770165109.628379"
+```
+
+### Create channels and invite users
+
+```bash
+# Create a public channel
+agent-slack channel new --name "incident-war-room"
+
+# Create a private channel
+agent-slack channel new --name "incident-leads" --private
+
+# Invite users by id, handle, or email
+agent-slack channel invite --channel "incident-war-room" --users "U01AAAA,@alice,bob@example.com"
+
+# Invite external Slack Connect users by email (restricted by default)
+agent-slack channel invite --channel "incident-war-room" --users "partner@vendor.com" --external
+
+# External invite with permission for invitees to invite others
+agent-slack channel invite --channel "incident-war-room" --users "partner@vendor.com" --external --allow-external-user-invites
+```
+
+Notes:
+
+- `--external` maps to `conversations.inviteShared` and expects email targets.
+- External invites default to restricted mode (`external_limited=true`); add `--allow-external-user-invites` to disable that restriction.
+- External invites require Slack Connect permissions/scopes in your workspace.
+
 ### Message get vs list
 
 **`message get`** fetches a single message. If the message is in a thread, it also returns thread metadata (reply count, participants) but **not** the full thread contents:
@@ -165,7 +239,7 @@ agent-slack message get "https://workspace.slack.com/archives/C123/p170000000000
 ```json
 {
   "message": { "ts": "...", "text": "...", "user": "U123", ... },
-  "thread": { "replyCount": 5, "participants": ["U123", "U456"] }
+  "thread": { "ts": "...", "length": 6 }
 }
 ```
 
@@ -185,6 +259,7 @@ When to use which:
 - Use `get` to check a single message or see if there's a thread worth expanding
 - Use `list` to read an entire thread conversation
 - Use `list` on a channel (without `--thread-ts`) to browse recent channel messages
+- Use `list` with `--with-reaction` / `--without-reaction` plus `--oldest` to filter channel history by reaction markers
 
 ### Files (snippets/images/attachments)
 
@@ -210,7 +285,7 @@ agent-slack search files "testing" --content-type snippet --limit 10
 Tips:
 
 - For reliable results, include `--channel ...` (channel-scoped search scans history/files and filters locally).
-- Use `--workspace https://...slack.com` when using `#channel` names across multiple workspaces.
+- Use `--workspace <url-or-unique-substring>` when using `#channel` names across multiple workspaces.
 
 <!-- AI search (assistant.search.*) is described in design.doc but not currently implemented. -->