agent-slack 0.2.13 → 0.3.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, detect threads, 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
-
-## Installation
+## Getting started
 
-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,14 @@ 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
+- **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
@@ -58,8 +58,10 @@ agent-slack
 │   └── parse-curl
 ├── message
 │   ├── get   <target>             # fetch 1 message (+ thread meta )
-│   ├── list  <target>             # fetch full thread
+│   ├── list  <target>             # fetch thread or recent channel messages
 │   ├── send  <target> <text>      # send / reply (does the right thing)
+│   ├── edit  <target> <text>      # edit a message
+│   ├── delete <target>            # delete a message
 │   └── react
 │       ├── add    <target> <emoji>
 │       └── remove <target> <emoji>
@@ -127,10 +129,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
@@ -146,6 +150,15 @@ agent-slack message get "https://workspace.slack.com/archives/C123/p170000000000
 
 # Full thread for a message
 agent-slack message list "https://workspace.slack.com/archives/C123/p1700000000000000"
+
+# 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:
@@ -155,6 +168,23 @@ Optional:
 agent-slack message get "https://workspace.slack.com/archives/C123/p1700000000000000" --include-reactions
 ```
 
+### 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"
+```
+
 ### 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:
@@ -162,11 +192,11 @@ 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 }
 }
 ```
 
-**`message list`** fetches all messages in a thread (or channel history if no thread). Use this when you need the full conversation:
+**`message list`** fetches all replies in a thread, or recent channel messages when no thread is specified. Use this when you need the full conversation:
 
 ```json
 {
@@ -181,6 +211,8 @@ 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)
 
@@ -206,7 +238,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. -->