From 898a0f84a1a8d668b0a8bf3c5a330930cf6ab396 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Sat, 30 May 2026 10:46:29 -0700
Subject: [PATCH] feat(message): schedule Slack messages

---
 README.md                                 |  36 ++-
 llms.txt                                  |   2 +-
 skills/agent-slack/SKILL.md               |  26 +-
 skills/agent-slack/references/commands.md |  19 ++
 skills/agent-slack/references/output.md   |  11 +
 src/cli/message-actions.ts                |  50 +++-
 src/cli/message-command.ts                |  28 ++-
 src/cli/message-scheduled-actions.ts      | 100 ++++++++
 src/cli/message-scheduled-command.ts      |  67 ++++++
 src/slack/scheduled-messages.ts           | 277 ++++++++++++++++++++++
 test/message-send.test.ts                 | 234 ++++++++++++++++++
 11 files changed, 841 insertions(+), 9 deletions(-)
 create mode 100644 src/cli/message-scheduled-actions.ts
 create mode 100644 src/cli/message-scheduled-command.ts
 create mode 100644 src/slack/scheduled-messages.ts

diff --git a/README.md b/README.md
index a70b9e3..82d6b64 100644
--- a/README.md
+++ b/README.md
@@ -34,7 +34,7 @@ nix run github:stablyai/agent-slack
 - **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 (bullet lists auto-render as native Slack rich text)
+- **Write**: send now or schedule delivery, edit/delete messages, add reactions (bullet lists auto-render as native Slack rich text)
 - **Channels**: list conversations, create channels, and invite users by id/handle/email
 - **Canvas**: fetch Slack canvases as Markdown
 
@@ -73,7 +73,10 @@ agent-slack
 ├── message
 │   ├── get   <target>             # fetch 1 message (+ thread meta )
 │   ├── list  <target>             # fetch thread or recent channel messages
-│   ├── send  <target> [text]      # send / reply (supports --attach, --blocks, --reply-broadcast)
+│   ├── send  <target> [text]      # send / reply / schedule (supports --attach, --blocks)
+│   ├── scheduled
+│   │   ├── list                   # list pending scheduled messages
+│   │   └── cancel <id>            # cancel a pending scheduled message
 │   ├── draft <target> [text]      # open Slack-like editor in browser
 │   ├── edit  <target> <text>      # edit a message
 │   ├── delete <target>            # delete a message
@@ -219,6 +222,8 @@ After sending, the editor shows a "View in Slack" link to the posted message.
 ```bash
 agent-slack message send "https://workspace.slack.com/archives/C123/p1700000000000000" "I can take this."
 agent-slack message send "#alerts-staging" "here's the report" --attach ./report.md
+agent-slack message send "#announcements" "Deploy starts at 6pm." --schedule "<future-iso-with-timezone>"
+agent-slack message send "U05BRPTKL6A" "Heads up before standup" --schedule-in "monday 9am"
 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"
@@ -239,6 +244,8 @@ Send options for `message send`:
 - `--attach <path>` upload a local file (repeatable; `<text>` is optional when attaching files)
 - `--blocks <path>` send raw [Block Kit](https://docs.slack.dev/block-kit/) blocks from a JSON file (or `-` for stdin). Bypasses the automatic markdown-to-rich-text conversion, unlocking header/divider/section/table blocks and other structured layouts. Cannot be combined with `--attach`.
 - `--reply-broadcast` when replying in a thread, also post the reply to the parent channel (Slack's "Also send to #channel" checkbox). For channel targets, pair with `--thread-ts`; for URL targets, the thread context is derived from the message. Not supported for DM targets; cannot be combined with `--attach`.
+- `--schedule <time>` schedule delivery at an ISO 8601 timestamp with explicit timezone (for example `YYYY-MM-DDTHH:mm:ss-07:00`) or a Unix timestamp. The timestamp must be in the future and within Slack's 120-day scheduled-send limit. Works with `--blocks`, `--thread-ts`, and `--reply-broadcast`; cannot be combined with `--attach`.
+- `--schedule-in <duration>` schedule delivery after a duration or simple future phrase (`30m`, `3h`, `2d`, `tomorrow 9am`, `monday 9am`; phrases use your local timezone). Mutually exclusive with `--schedule`; cannot be combined with `--attach`.
 
 Upload files through `message send`:
 
@@ -253,6 +260,29 @@ agent-slack message send "#general" "Decision: shipping v2 today" \
   --thread-ts "1770160000.000001" --reply-broadcast
 ```
 
+Scheduled sends use Slack's server-side scheduled message queue:
+
+```bash
+# Absolute time with explicit timezone; replace with a future value within 120 days
+agent-slack message send "#general" "Reminder: deploy starts soon." \
+  --schedule "<future-iso-with-timezone>"
+
+# Relative / natural future time
+agent-slack message send "#general" "Monday launch checklist" --schedule-in "monday 9am"
+
+# Scheduled thread reply with a Block Kit payload
+agent-slack message send "#general" "fallback text" \
+  --thread-ts "1770160000.000001" --blocks /tmp/blocks.json --schedule-in "3h"
+```
+
+Manage pending scheduled messages:
+
+```bash
+agent-slack message scheduled list
+agent-slack message scheduled list --channel "#general" --limit 25
+agent-slack message scheduled cancel "Q1234ABCD" --channel "C12345678"
+```
+
 Example — post a message with a native Slack table block:
 
 ```bash
@@ -282,7 +312,7 @@ agent-slack message send "#alerts-staging" --blocks /tmp/blocks.json
 
 When `--blocks` is used, the positional `<text>` argument (if provided) is still sent as the message's `text` fallback (for notifications and unfurls).
 
-`message send` returns `channel_id` plus the posted `ts` and a `permalink` (for non-attachment sends). `thread_ts` appears only when replying in a thread.
+`message send` returns `channel_id` plus the posted `ts` and a `permalink` (for non-attachment sends). `thread_ts` appears only when replying in a thread. Scheduled sends return `scheduled_message_id` and `post_at` instead of `ts`/`permalink`.
 
 ### List, create, and invite channels
 
diff --git a/llms.txt b/llms.txt
index 298204e..149dbf4 100644
--- a/llms.txt
+++ b/llms.txt
@@ -12,7 +12,7 @@
 
 - Read Slack messages, threads, and channel history from any URL or channel name
 - Search Slack messages and files with filters for channel, user, date, and content type
-- Send, edit, delete Slack messages, upload local files with `message send --attach`, and add/remove emoji reactions programmatically
+- Send, schedule, edit, delete Slack messages, upload local files with `message send --attach`, and add/remove emoji reactions programmatically
 - Auto-download Slack file attachments (snippets, images, files) to local paths for AI agent consumption
 - Token-efficient compact JSON output so LLMs can consume Slack data cheaply
 - Zero-config auth: auto-detects Slack Desktop credentials on macOS, Windows, and Linux — with Chrome, Brave, and Firefox fallbacks
diff --git a/skills/agent-slack/SKILL.md b/skills/agent-slack/SKILL.md
index 5fe76d8..8bfa816 100644
--- a/skills/agent-slack/SKILL.md
+++ b/skills/agent-slack/SKILL.md
@@ -6,7 +6,7 @@ description: |
   - Browsing recent channel messages / channel history
   - Downloading Slack attachments (snippets, images, files) to local paths
   - Searching Slack messages or files
-  - Sending messages, including local file uploads via `message send --attach`
+  - Sending messages, including scheduled delivery and local file uploads via `message send --attach`
   - Editing or deleting a message; adding/removing reactions
   - Listing channels/conversations; creating channels and inviting users
   - Fetching a Slack canvas as markdown
@@ -16,7 +16,7 @@ description: |
   - Discovering and running Slack workflows
   - Managing saved-for-later messages (Later tab)
   - Viewing all unread messages (inbox/unreads view)
-  Triggers: "slack message", "slack thread", "slack URL", "slack link", "read slack", "reply on slack", "search slack", "channel history", "recent messages", "channel messages", "latest messages", "mark as read", "mark read", "slack later", "saved for later", "save for later", "slack unreads", "slack inbox", "unread slack", "upload file", "slack file upload", "send file slack"
+  Triggers: "slack message", "slack thread", "slack URL", "slack link", "read slack", "reply on slack", "search slack", "channel history", "recent messages", "channel messages", "latest messages", "schedule slack", "scheduled slack", "scheduled message", "mark as read", "mark read", "slack later", "saved for later", "save for later", "slack unreads", "slack inbox", "unread slack", "upload file", "slack file upload", "send file slack"
 ---
 
 # Slack automation with `agent-slack`
@@ -148,6 +148,8 @@ agent-slack message draft "https://workspace.slack.com/archives/C123/p1700000000
 ```bash
 agent-slack message send "https://workspace.slack.com/archives/C123/p1700000000000000" "I can take this."
 agent-slack message send "alerts-staging" "here's the report" --attach ./report.md
+agent-slack message send "announcements" "Deploy starts at 6pm." --schedule "<future-iso-with-timezone>"
+agent-slack message send "U05BRPTKL6A" "Heads up before standup" --schedule-in "monday 9am"
 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"
 
@@ -173,6 +175,8 @@ Send options for `message send`:
 - `--attach <path>` upload a local file (repeatable; message text is optional when attaching files)
 - `--blocks <path>` send raw [Block Kit](https://docs.slack.dev/block-kit/) blocks from a JSON file (or `-` for stdin). Enables headers, dividers, table blocks, and other structured layouts. Incompatible with `--attach`.
 - `--reply-broadcast` when replying in a thread, also post the reply to the parent channel (Slack's "Also send to #channel" checkbox). For channel targets, pair with `--thread-ts`; for URL targets, the thread context is derived from the message. Not supported for DM targets; incompatible with `--attach`.
+- `--schedule <time>` schedule delivery at an ISO 8601 timestamp with explicit timezone (for example `YYYY-MM-DDTHH:mm:ss-07:00`) or a Unix timestamp. The timestamp must be in the future and within Slack's 120-day scheduled-send limit. Works with `--blocks`, `--thread-ts`, and `--reply-broadcast`; incompatible with `--attach`.
+- `--schedule-in <duration>` schedule delivery after a duration or simple future phrase (`30m`, `3h`, `2d`, `tomorrow 9am`, `monday 9am`; phrases use your local timezone). Mutually exclusive with `--schedule`; incompatible with `--attach`.
 
 File upload example:
 
@@ -187,7 +191,23 @@ agent-slack message send "general" "Decision: shipping v2 today" \
   --thread-ts "1770160000.000001" --reply-broadcast
 ```
 
-`message send` returns `channel_id` plus the posted `ts` and a `permalink` (for non-attachment sends). `thread_ts` appears only when replying in a thread.
+Schedule a message:
+
+```bash
+agent-slack message send "general" "Reminder: deploy starts soon." --schedule "<future-iso-with-timezone>"
+agent-slack message send "general" "Monday launch checklist" --schedule-in "monday 9am"
+agent-slack message send "general" "fallback text" --thread-ts "1770160000.000001" --blocks /tmp/blocks.json --schedule-in "3h"
+```
+
+Manage pending scheduled messages:
+
+```bash
+agent-slack message scheduled list
+agent-slack message scheduled list --channel "general" --limit 25
+agent-slack message scheduled cancel "Q1234ABCD" --channel "C12345678"
+```
+
+`message send` returns `channel_id` plus the posted `ts` and a `permalink` (for non-attachment sends). `thread_ts` appears only when replying in a thread. Scheduled sends return `scheduled_message_id` and `post_at` instead of `ts`/`permalink`.
 
 Mentions: just write `@U05BRPTKL6A`, `@here`, `@channel`, or `@everyone` — the CLI converts them to real Slack mention tokens and escapes literal `&`/`<`/`>` in your text. You don't need to wrap IDs yourself.
 
diff --git a/skills/agent-slack/references/commands.md b/skills/agent-slack/references/commands.md
index 8c88d6c..3e31668 100644
--- a/skills/agent-slack/references/commands.md
+++ b/skills/agent-slack/references/commands.md
@@ -66,12 +66,31 @@ Run `agent-slack --help` (or `agent-slack <command> --help`) for the full option
   - `[text]` is optional when uploading files with `--attach`; when present, it becomes the initial comment on the first uploaded file.
   - Bullet lists (`- `, `* `, `• `, `1. `, etc.) are automatically converted to Slack’s native rich text format, so recipients see real editable bullets instead of plain-text dashes.
   - Example: `agent-slack message send "general" "Coverage report" --attach ./report.md`
+  - Example: `agent-slack message send "general" "Monday launch checklist" --schedule-in "monday 9am"`
   - Options:
     - `--workspace <url-or-unique-substring>` (needed for channel _names_ across multiple workspaces)
     - `--thread-ts <seconds>.<micros>` (optional, channel mode only)
     - `--attach <path>` (repeatable; upload local files as attachments)
     - `--blocks <path>` raw Block Kit blocks from a JSON file (or `-` for stdin). Bypasses markdown-to-rich-text conversion; enables header/divider/section/table blocks. Cannot be combined with `--attach`.
     - `--reply-broadcast` when replying in a thread, also post the reply to the parent channel. For channel targets, pair with `--thread-ts`; for URL targets, the thread context is derived from the message. Not supported for DM targets; cannot be combined with `--attach`.
+    - `--schedule <time>` schedule delivery at an ISO 8601 timestamp with explicit timezone (or Unix timestamp). Must be in the future and within Slack's 120-day scheduled-send limit. Compatible with `--blocks`, `--thread-ts`, and `--reply-broadcast`; cannot be combined with `--attach`.
+    - `--schedule-in <duration>` schedule delivery after a duration or simple future phrase (`30m`, `3h`, `2d`, `tomorrow 9am`, `monday 9am`; phrases use your local timezone). Mutually exclusive with `--schedule`; cannot be combined with `--attach`.
+
+- `agent-slack message scheduled list`
+  - Lists pending scheduled messages from Slack's server-side scheduled message queue.
+  - Options:
+    - `--workspace <url-or-unique-substring>` (defaults to configured workspace)
+    - `--channel <channel>` filter to a channel/DM id or channel name
+    - `--oldest <unix-ts>` only messages scheduled after this time
+    - `--latest <unix-ts>` only messages scheduled before this time
+    - `--cursor <cursor>` fetch the next page
+    - `--limit <n>` max messages to return
+
+- `agent-slack message scheduled cancel <scheduled_message_id>`
+  - Cancels a pending scheduled message before it is sent.
+  - Options:
+    - `--channel <channel>` required channel/DM id or channel name for the scheduled message
+    - `--workspace <url-or-unique-substring>` (needed for channel _names_ across multiple workspaces)
 
 - `agent-slack message edit <target> <text>`
   - URL target edits that exact message.
diff --git a/skills/agent-slack/references/output.md b/skills/agent-slack/references/output.md
index 55b5acb..df61459 100644
--- a/skills/agent-slack/references/output.md
+++ b/skills/agent-slack/references/output.md
@@ -25,6 +25,17 @@ All commands print JSON to stdout.
   - `ts?: "<seconds>.<micros>"` — the posted message's ts; absent on file-attachment sends
   - `thread_ts?: "<seconds>.<micros>"` — present only when the send was into an existing thread
   - `permalink?: "https://.../archives/..."` — present when `ts` is known and a workspace URL was resolvable
+  - `scheduled_message_id?: "Q..."` — present for `--schedule` / `--schedule-in` sends
+  - `post_at?: <unix-seconds>` — present for scheduled sends
+
+- `message scheduled list` returns:
+  - `scheduled_messages: [{ id, channel_id, post_at, date_created?, text? }]`
+  - `next_cursor?: "<cursor>"`
+
+- `message scheduled cancel` returns:
+  - `ok: true`
+  - `channel_id: "C..." | "D..."`
+  - `scheduled_message_id: "Q..."`
 
 Message payload fields keep canonical user IDs (for example `author.user_id`, reaction `users[]`, and `@U...` mentions in rendered content).
 `referenced_users` provides display metadata for those IDs. The cache is per-workspace with a 24-hour per-entry TTL.
diff --git a/src/cli/message-actions.ts b/src/cli/message-actions.ts
index 8fbaf82..2db0465 100644
--- a/src/cli/message-actions.ts
+++ b/src/cli/message-actions.ts
@@ -10,6 +10,7 @@ import { formatOutboundSlackText } from "../slack/format-outbound.ts";
 import type { SlackApiClient } from "../slack/client.ts";
 import { uploadLocalFileToSlack } from "../slack/upload.ts";
 import { buildSlackMessageUrl } from "../slack/url.ts";
+import { resolveSchedulePostAt } from "../slack/scheduled-messages.ts";
 
 function loadBlocksFromPath(path: string): unknown[] {
   const raw = path === "-" ? readFileSync(0, "utf8") : readFileSync(path, "utf8");
@@ -111,16 +112,27 @@ export async function sendMessage(input: {
     attach?: string[];
     blocks?: string;
     replyBroadcast?: boolean;
+    schedule?: string;
+    scheduleIn?: string;
   };
 }): Promise<Record<string, unknown>> {
   const target = parseMsgTarget(String(input.targetInput));
+  const attachPaths = normalizeAttachPaths(input.options.attach);
+  const postAt = resolveSchedulePostAt({
+    schedule: input.options.schedule,
+    scheduleIn: input.options.scheduleIn,
+  });
+  if (postAt !== undefined && attachPaths.length > 0) {
+    throw new Error(
+      "--schedule/--schedule-in cannot be combined with --attach (Slack scheduled messages do not support file uploads).",
+    );
+  }
   const formattedText = formatOutboundSlackText(input.text);
   const blocks = input.options.blocks
     ? loadBlocksFromPath(input.options.blocks)
     : input.text
       ? textToRichTextBlocks(input.text)
       : null;
-  const attachPaths = normalizeAttachPaths(input.options.attach);
 
   if (target.kind === "url") {
     const { ref } = target;
@@ -140,6 +152,7 @@ export async function sendMessage(input: {
           threadTs,
           replyBroadcast: input.options.replyBroadcast,
           attachPaths,
+          postAt,
         });
       },
     });
@@ -162,6 +175,7 @@ export async function sendMessage(input: {
           text: formattedText,
           blocks,
           attachPaths,
+          postAt,
         });
       },
     });
@@ -189,6 +203,7 @@ export async function sendMessage(input: {
         threadTs: input.options.threadTs ? String(input.options.threadTs) : undefined,
         replyBroadcast: input.options.replyBroadcast,
         attachPaths,
+        postAt,
       });
     },
   });
@@ -216,7 +231,29 @@ async function sendMessageToChannel(input: {
   threadTs?: string;
   replyBroadcast?: boolean;
   attachPaths: string[];
+  postAt?: number;
 }): Promise<Record<string, unknown>> {
+  if (input.postAt !== undefined) {
+    const resp = await input.client.api("chat.scheduleMessage", {
+      channel: input.channelId,
+      text: input.text,
+      post_at: input.postAt,
+      thread_ts: input.threadTs,
+      ...(input.blocks ? { blocks: input.blocks } : {}),
+      ...(input.replyBroadcast && input.threadTs ? { reply_broadcast: true } : {}),
+    });
+    const channelId = typeof resp.channel === "string" ? resp.channel : input.channelId;
+    const scheduledMessageId =
+      typeof resp.scheduled_message_id === "string" ? resp.scheduled_message_id : undefined;
+    return {
+      ok: true,
+      channel_id: channelId,
+      scheduled_message_id: scheduledMessageId,
+      post_at: getResponseNumber(resp.post_at) ?? input.postAt,
+      thread_ts: input.threadTs,
+    };
+  }
+
   if (input.attachPaths.length === 0) {
     const resp = await input.client.api("chat.postMessage", {
       channel: input.channelId,
@@ -270,6 +307,17 @@ async function sendMessageToChannel(input: {
   };
 }
 
+function getResponseNumber(value: unknown): number | undefined {
+  if (typeof value === "number") {
+    return value;
+  }
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+}
+
 export async function editMessage(input: {
   ctx: CliContext;
   targetInput: string;
diff --git a/src/cli/message-command.ts b/src/cli/message-command.ts
index 8f93bc1..4ab593b 100644
--- a/src/cli/message-command.ts
+++ b/src/cli/message-command.ts
@@ -10,6 +10,7 @@ import {
   type MessageCommandOptions,
 } from "./message-actions.ts";
 import { draftMessage } from "./draft-actions.ts";
+import { registerScheduledMessageCommand } from "./message-scheduled-command.ts";
 
 function collectOptionValue(value: string, previous: string[] = []): string[] {
   return [...previous, value];
@@ -155,7 +156,7 @@ export function registerMessageCommand(input: { program: Command; ctx: CliContex
 
   messageCmd
     .command("send")
-    .description("Send a message (optionally into a thread)")
+    .description("Send or schedule a message (optionally into a thread)")
     .argument("<target>", "Slack message URL, #name/name, or channel id")
     .argument("[text]", "Message text to post (optional when using --attach)")
     .option(
@@ -172,6 +173,14 @@ export function registerMessageCommand(input: { program: Command; ctx: CliContex
       "--blocks <path>",
       "Path to a JSON file containing a Block Kit blocks array. Bypasses automatic markdown-to-rich-text conversion. Use '-' to read from stdin. Cannot be combined with --attach.",
     )
+    .option(
+      "--schedule <time>",
+      "Schedule delivery at an ISO 8601 timestamp with explicit timezone (or Unix timestamp). Cannot be combined with --attach.",
+    )
+    .option(
+      "--schedule-in <duration>",
+      "Schedule delivery after a duration or future phrase, e.g. 3h, tomorrow 9am, monday 9am. Cannot be combined with --attach.",
+    )
     .action(async (...args) => {
       const [targetInput, text, options] = args as [
         string,
@@ -182,10 +191,13 @@ export function registerMessageCommand(input: { program: Command; ctx: CliContex
           attach?: string[];
           blocks?: string;
           replyBroadcast?: boolean;
+          schedule?: string;
+          scheduleIn?: string;
         },
       ];
       const hasAttach = (options.attach ?? []).length > 0;
       const hasBlocks = options.blocks !== undefined;
+      const hasSchedule = options.schedule !== undefined || options.scheduleIn !== undefined;
       if (!text && !hasAttach && !hasBlocks) {
         console.error("Error: <text> is required when no --attach files or --blocks are provided.");
         process.exitCode = 1;
@@ -203,6 +215,18 @@ export function registerMessageCommand(input: { program: Command; ctx: CliContex
         process.exitCode = 1;
         return;
       }
+      if (options.schedule !== undefined && options.scheduleIn !== undefined) {
+        console.error("Error: --schedule and --schedule-in are mutually exclusive.");
+        process.exitCode = 1;
+        return;
+      }
+      if (hasSchedule && hasAttach) {
+        console.error(
+          "Error: --schedule/--schedule-in cannot be combined with --attach (Slack scheduled messages do not support file uploads).",
+        );
+        process.exitCode = 1;
+        return;
+      }
       try {
         const payload = await sendMessage({
           ctx: input.ctx,
@@ -217,6 +241,8 @@ export function registerMessageCommand(input: { program: Command; ctx: CliContex
       }
     });
 
+  registerScheduledMessageCommand({ messageCmd, ctx: input.ctx });
+
   messageCmd
     .command("draft")
     .description("Open a rich Slack-like editor to compose and send a message")
diff --git a/src/cli/message-scheduled-actions.ts b/src/cli/message-scheduled-actions.ts
new file mode 100644
index 0000000..faeef35
--- /dev/null
+++ b/src/cli/message-scheduled-actions.ts
@@ -0,0 +1,100 @@
+import type { CliContext } from "./context.ts";
+import { parseMsgTarget } from "./targets.ts";
+import { openDmChannel, resolveChannelId } from "../slack/channels.ts";
+import type { SlackApiClient } from "../slack/client.ts";
+import {
+  cancelScheduledMessage as cancelScheduledMessageApi,
+  listScheduledMessages as listScheduledMessagesApi,
+  normalizeScheduleLimit,
+} from "../slack/scheduled-messages.ts";
+
+export async function listScheduledMessages(input: {
+  ctx: CliContext;
+  options: {
+    workspace?: string;
+    channel?: string;
+    cursor?: string;
+    oldest?: string;
+    latest?: string;
+    limit?: string;
+  };
+}): Promise<Record<string, unknown>> {
+  const channelTarget = input.options.channel
+    ? parseMsgTarget(String(input.options.channel))
+    : undefined;
+  const workspaceUrl =
+    channelTarget?.kind === "url"
+      ? channelTarget.ref.workspace_url
+      : input.ctx.effectiveWorkspaceUrl(input.options.workspace);
+  if (channelTarget?.kind === "channel") {
+    await input.ctx.assertWorkspaceSpecifiedForChannelNames({
+      workspaceUrl,
+      channels: [channelTarget.channel],
+    });
+  }
+
+  return await input.ctx.withAutoRefresh({
+    workspaceUrl,
+    work: async () => {
+      const { client } = await input.ctx.getClientForWorkspace(workspaceUrl);
+      const channelId = channelTarget
+        ? await resolveScheduledChannelTarget(client, channelTarget)
+        : undefined;
+      return await listScheduledMessagesApi(client, {
+        channelId,
+        cursor: input.options.cursor,
+        oldest: input.options.oldest,
+        latest: input.options.latest,
+        limit: normalizeScheduleLimit(input.options.limit),
+      });
+    },
+  });
+}
+
+export async function cancelScheduledMessage(input: {
+  ctx: CliContext;
+  scheduledMessageId: string;
+  options: { workspace?: string; channel: string };
+}): Promise<Record<string, unknown>> {
+  const channelTarget = parseMsgTarget(String(input.options.channel));
+  const workspaceUrl =
+    channelTarget.kind === "url"
+      ? channelTarget.ref.workspace_url
+      : input.ctx.effectiveWorkspaceUrl(input.options.workspace);
+  if (channelTarget.kind === "channel") {
+    await input.ctx.assertWorkspaceSpecifiedForChannelNames({
+      workspaceUrl,
+      channels: [channelTarget.channel],
+    });
+  }
+
+  return await input.ctx.withAutoRefresh({
+    workspaceUrl,
+    work: async () => {
+      const { client } = await input.ctx.getClientForWorkspace(workspaceUrl);
+      const channelId = await resolveScheduledChannelTarget(client, channelTarget);
+      await cancelScheduledMessageApi(client, {
+        channelId,
+        scheduledMessageId: input.scheduledMessageId,
+      });
+      return {
+        ok: true,
+        channel_id: channelId,
+        scheduled_message_id: input.scheduledMessageId,
+      };
+    },
+  });
+}
+
+async function resolveScheduledChannelTarget(
+  client: SlackApiClient,
+  target: ReturnType<typeof parseMsgTarget>,
+): Promise<string> {
+  if (target.kind === "url") {
+    return target.ref.channel_id;
+  }
+  if (target.kind === "user") {
+    return await openDmChannel(client, target.userId);
+  }
+  return await resolveChannelId(client, target.channel);
+}
diff --git a/src/cli/message-scheduled-command.ts b/src/cli/message-scheduled-command.ts
new file mode 100644
index 0000000..e41228b
--- /dev/null
+++ b/src/cli/message-scheduled-command.ts
@@ -0,0 +1,67 @@
+import type { Command } from "commander";
+import type { CliContext } from "./context.ts";
+import { cancelScheduledMessage, listScheduledMessages } from "./message-scheduled-actions.ts";
+
+export function registerScheduledMessageCommand(input: {
+  messageCmd: Command;
+  ctx: CliContext;
+}): void {
+  const scheduledCmd = input.messageCmd
+    .command("scheduled")
+    .description("List or cancel pending scheduled messages");
+
+  scheduledCmd
+    .command("list", { isDefault: true })
+    .description("List pending scheduled messages")
+    .option("--workspace <url>", "Workspace selector (full URL or unique substring)")
+    .option("--channel <channel>", "Limit to a channel/DM id or channel name")
+    .option("--oldest <ts>", "Only messages scheduled after this Unix timestamp")
+    .option("--latest <ts>", "Only messages scheduled before this Unix timestamp")
+    .option("--cursor <cursor>", "Fetch the next page from chat.scheduledMessages.list")
+    .option("--limit <n>", "Max scheduled messages to return")
+    .action(
+      async (options: {
+        workspace?: string;
+        channel?: string;
+        oldest?: string;
+        latest?: string;
+        cursor?: string;
+        limit?: string;
+      }) => {
+        try {
+          const payload = await listScheduledMessages({ ctx: input.ctx, options });
+          console.log(JSON.stringify(payload, null, 2));
+        } catch (err: unknown) {
+          console.error(input.ctx.errorMessage(err));
+          process.exitCode = 1;
+        }
+      },
+    );
+
+  scheduledCmd
+    .command("cancel")
+    .description("Cancel a pending scheduled message")
+    .argument("<id>", "scheduled_message_id returned by message send --schedule")
+    .requiredOption(
+      "--channel <channel>",
+      "Channel/DM id or channel name for the scheduled message",
+    )
+    .option("--workspace <url>", "Workspace selector (full URL or unique substring)")
+    .action(async (...args) => {
+      const [scheduledMessageId, options] = args as [
+        string,
+        { workspace?: string; channel: string },
+      ];
+      try {
+        const payload = await cancelScheduledMessage({
+          ctx: input.ctx,
+          scheduledMessageId,
+          options,
+        });
+        console.log(JSON.stringify(payload, null, 2));
+      } catch (err: unknown) {
+        console.error(input.ctx.errorMessage(err));
+        process.exitCode = 1;
+      }
+    });
+}
diff --git a/src/slack/scheduled-messages.ts b/src/slack/scheduled-messages.ts
new file mode 100644
index 0000000..abb7aeb
--- /dev/null
+++ b/src/slack/scheduled-messages.ts
@@ -0,0 +1,277 @@
+import type { SlackApiClient } from "./client.ts";
+import { asArray, getNumber, getString, isRecord } from "../lib/object-type-guards.ts";
+
+const MAX_SCHEDULE_SECONDS = 120 * 24 * 60 * 60;
+const DEFAULT_NAMED_TIME = { hour: 9, minute: 0 };
+
+type Clock = {
+  now?: Date;
+};
+
+export type ScheduledMessage = Record<string, unknown>;
+
+export async function listScheduledMessages(
+  client: SlackApiClient,
+  options?: {
+    channelId?: string;
+    cursor?: string;
+    oldest?: string;
+    latest?: string;
+    limit?: number;
+  },
+): Promise<{
+  ok: true;
+  scheduled_messages: ScheduledMessage[];
+  next_cursor?: string;
+}> {
+  const resp = await client.api("chat.scheduledMessages.list", {
+    channel: options?.channelId,
+    cursor: options?.cursor,
+    oldest: options?.oldest,
+    latest: options?.latest,
+    limit: options?.limit,
+  });
+  const meta = isRecord(resp.response_metadata) ? resp.response_metadata : null;
+  const nextCursor = meta ? getString(meta.next_cursor) : undefined;
+  return {
+    ok: true,
+    scheduled_messages: asArray(resp.scheduled_messages).filter(isRecord),
+    next_cursor: nextCursor,
+  };
+}
+
+export async function cancelScheduledMessage(
+  client: SlackApiClient,
+  input: { channelId: string; scheduledMessageId: string },
+): Promise<void> {
+  await client.api("chat.deleteScheduledMessage", {
+    channel: input.channelId,
+    scheduled_message_id: input.scheduledMessageId,
+  });
+}
+
+export function resolveSchedulePostAt(
+  input: { schedule?: string; scheduleIn?: string },
+  clock?: Clock,
+): number | undefined {
+  const at = input.schedule?.trim();
+  const within = input.scheduleIn?.trim();
+  if (at && within) {
+    throw new Error("--schedule and --schedule-in are mutually exclusive.");
+  }
+  if (!at && !within) {
+    return undefined;
+  }
+
+  const postAt = at ? parseAbsoluteSchedule(at) : parseRelativeSchedule(within ?? "", clock);
+  validatePostAt(postAt, clock);
+  return postAt;
+}
+
+export function parseAbsoluteSchedule(input: string): number {
+  const trimmed = input.trim();
+  const unix = parseUnixTimestamp(trimmed);
+  if (unix !== undefined) {
+    return unix;
+  }
+
+  if (!hasExplicitIsoTimezone(trimmed)) {
+    throw new Error(
+      `Invalid --schedule value "${input}". Use an ISO 8601 timestamp with an explicit timezone (YYYY-MM-DDTHH:mm:ss-07:00), or a Unix timestamp.`,
+    );
+  }
+
+  const ms = Date.parse(trimmed);
+  if (!Number.isFinite(ms)) {
+    throw new Error(
+      `Invalid --schedule value "${input}". Use an ISO 8601 timestamp with an explicit timezone (YYYY-MM-DDTHH:mm:ss-07:00), or a Unix timestamp.`,
+    );
+  }
+  return Math.floor(ms / 1000);
+}
+
+export function parseRelativeSchedule(input: string, clock?: Clock): number {
+  const now = clock?.now ? new Date(clock.now) : new Date();
+  const trimmed = input.trim().toLowerCase();
+  if (!trimmed) {
+    throw new Error(
+      'Invalid --schedule-in value "". Use: 30m, 1h, 3h, 2d, tomorrow 9am, monday 9am, or a Unix timestamp.',
+    );
+  }
+
+  const unix = parseUnixTimestamp(trimmed);
+  if (unix !== undefined) {
+    return unix;
+  }
+
+  const relMatch = trimmed.match(
+    /^(\d+(?:\.\d+)?)\s*(m|min|mins|minutes?|h|hr|hrs|hours?|d|day|days?)$/,
+  );
+  if (relMatch) {
+    const amount = Number.parseFloat(relMatch[1]!);
+    const unit = relMatch[2]!.charAt(0);
+    const seconds = unit === "m" ? amount * 60 : unit === "h" ? amount * 3600 : amount * 86400;
+    return Math.floor(now.getTime() / 1000 + seconds);
+  }
+
+  const named = parseNamedFutureTime(trimmed, now);
+  if (named !== undefined) {
+    return named;
+  }
+
+  throw new Error(
+    `Invalid --schedule-in value "${input}". Use: 30m, 1h, 3h, 2d, tomorrow 9am, monday 9am, or a Unix timestamp.`,
+  );
+}
+
+export function normalizeScheduleLimit(raw: string | undefined): number | undefined {
+  if (raw === undefined) {
+    return undefined;
+  }
+  const limit = Number.parseInt(raw, 10);
+  if (!Number.isFinite(limit) || limit < 1) {
+    throw new Error(`Invalid --limit value "${raw}": must be a positive integer`);
+  }
+  return limit;
+}
+
+function validatePostAt(postAt: number, clock?: Clock): void {
+  const now = Math.floor((clock?.now ? clock.now.getTime() : Date.now()) / 1000);
+  if (!Number.isFinite(postAt) || postAt <= now) {
+    throw new Error("--schedule/--schedule-in must resolve to a future time.");
+  }
+  if (postAt > now + MAX_SCHEDULE_SECONDS) {
+    throw new Error("--schedule/--schedule-in cannot be more than 120 days in the future.");
+  }
+}
+
+function parseUnixTimestamp(input: string): number | undefined {
+  if (!/^\d+(?:\.\d+)?$/.test(input)) {
+    return undefined;
+  }
+  const n = Number(input);
+  if (!Number.isFinite(n) || n < 1_000_000_000) {
+    return undefined;
+  }
+  return Math.floor(n);
+}
+
+function hasExplicitIsoTimezone(input: string): boolean {
+  return /^\d{4}-\d{2}-\d{2}t\d{2}:\d{2}/i.test(input) && /(?:z|[+-]\d{2}:?\d{2})$/i.test(input);
+}
+
+function parseNamedFutureTime(input: string, now: Date): number | undefined {
+  const parts = input.split(/\s+/).filter(Boolean);
+  if (parts.length < 1 || parts.length > 3) {
+    return undefined;
+  }
+
+  const hasNext = parts[0] === "next";
+  const dayToken = hasNext ? parts[1] : parts[0];
+  const timeText = hasNext ? parts.slice(2).join(" ") : parts.slice(1).join(" ");
+  if (!dayToken) {
+    return undefined;
+  }
+
+  const time = timeText ? parseTimeOfDay(timeText) : DEFAULT_NAMED_TIME;
+  if (!time) {
+    return undefined;
+  }
+
+  if (dayToken === "today") {
+    const date = withLocalTime({ base: now, daysFromNow: 0, time });
+    return date.getTime() > now.getTime() ? Math.floor(date.getTime() / 1000) : undefined;
+  }
+
+  if (dayToken === "tomorrow" || dayToken === "tmrw") {
+    return Math.floor(withLocalTime({ base: now, daysFromNow: 1, time }).getTime() / 1000);
+  }
+
+  const targetDay = weekdayIndex(dayToken);
+  if (targetDay === undefined) {
+    return undefined;
+  }
+
+  const currentDay = now.getDay();
+  let daysUntil = targetDay - currentDay;
+  if (daysUntil < 0 || hasNext) {
+    daysUntil += 7;
+  }
+
+  let candidate = withLocalTime({ base: now, daysFromNow: daysUntil, time });
+  if (candidate.getTime() <= now.getTime()) {
+    candidate = withLocalTime({ base: now, daysFromNow: daysUntil + 7, time });
+  }
+  return Math.floor(candidate.getTime() / 1000);
+}
+
+function parseTimeOfDay(input: string): { hour: number; minute: number } | undefined {
+  const normalized = input.trim().toLowerCase().replace(/\s+/g, "");
+  if (normalized === "noon") {
+    return { hour: 12, minute: 0 };
+  }
+  if (normalized === "midnight") {
+    return { hour: 0, minute: 0 };
+  }
+
+  const match = normalized.match(/^(\d{1,2})(?::(\d{2}))?(am|pm)?$/);
+  if (!match) {
+    return undefined;
+  }
+  const [, hourRaw, minuteRaw, meridiem] = match;
+  let hour = Number.parseInt(hourRaw!, 10);
+  const minute = minuteRaw ? Number.parseInt(minuteRaw, 10) : 0;
+  if (!Number.isInteger(hour) || !Number.isInteger(minute) || minute < 0 || minute > 59) {
+    return undefined;
+  }
+
+  if (meridiem) {
+    if (hour < 1 || hour > 12) {
+      return undefined;
+    }
+    if (meridiem === "am") {
+      hour = hour === 12 ? 0 : hour;
+    } else {
+      hour = hour === 12 ? 12 : hour + 12;
+    }
+  } else if (hour < 0 || hour > 23) {
+    return undefined;
+  }
+
+  return { hour, minute };
+}
+
+function withLocalTime(input: {
+  base: Date;
+  daysFromNow: number;
+  time: { hour: number; minute: number };
+}): Date {
+  const { base, daysFromNow, time } = input;
+  const date = new Date(base);
+  date.setDate(base.getDate() + daysFromNow);
+  date.setHours(time.hour, time.minute, 0, 0);
+  return date;
+}
+
+function weekdayIndex(input: string): number | undefined {
+  const days = new Map<string, number>([
+    ["sun", 0],
+    ["sunday", 0],
+    ["mon", 1],
+    ["monday", 1],
+    ["tue", 2],
+    ["tues", 2],
+    ["tuesday", 2],
+    ["wed", 3],
+    ["wednesday", 3],
+    ["thu", 4],
+    ["thur", 4],
+    ["thurs", 4],
+    ["thursday", 4],
+    ["fri", 5],
+    ["friday", 5],
+    ["sat", 6],
+    ["saturday", 6],
+  ]);
+  return getNumber(days.get(input));
+}
diff --git a/test/message-send.test.ts b/test/message-send.test.ts
index 6726dff..6dcf134 100644
--- a/test/message-send.test.ts
+++ b/test/message-send.test.ts
@@ -4,6 +4,15 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { CliContext } from "../src/cli/context.ts";
 import { editMessage, sendMessage } from "../src/cli/message-actions.ts";
+import {
+  cancelScheduledMessage,
+  listScheduledMessages,
+} from "../src/cli/message-scheduled-actions.ts";
+import {
+  parseAbsoluteSchedule,
+  parseRelativeSchedule,
+  resolveSchedulePostAt,
+} from "../src/slack/scheduled-messages.ts";
 
 function createContext(calls: { method: string; params: Record<string, unknown> }[]) {
   const client = {
@@ -15,6 +24,40 @@ function createContext(calls: { method: string; params: Record<string, unknown>
       if (method === "chat.postMessage") {
         return { ok: true, channel: String(params.channel), ts: "1770165109.628379" };
       }
+      if (method === "chat.scheduleMessage") {
+        return {
+          ok: true,
+          channel: String(params.channel),
+          scheduled_message_id: "Q1234ABCD",
+          post_at: String(params.post_at),
+        };
+      }
+      if (method === "chat.scheduledMessages.list") {
+        return {
+          ok: true,
+          scheduled_messages: [
+            {
+              id: "Q1234ABCD",
+              channel_id: String(params.channel ?? "C12345678"),
+              post_at: 1770168709,
+              text: "scheduled",
+            },
+          ],
+          response_metadata: { next_cursor: "next-1" },
+        };
+      }
+      if (method === "chat.deleteScheduledMessage") {
+        return { ok: true };
+      }
+      if (method === "search.messages") {
+        return {
+          ok: true,
+          messages: { matches: [{ channel: { id: "C12345678", name: "general" } }] },
+        };
+      }
+      if (method === "conversations.open") {
+        return { ok: true, channel: { id: "D12345678" } };
+      }
       return { ok: true };
     },
   };
@@ -490,6 +533,197 @@ describe("sendMessage", () => {
       await rm(dir, { recursive: true, force: true });
     }
   });
+
+  test("--schedule sends through chat.scheduleMessage and returns scheduled metadata", async () => {
+    const calls: { method: string; params: Record<string, unknown> }[] = [];
+    const ctx = createContext(calls);
+    const when = new Date(Date.now() + 60 * 60 * 1000).toISOString();
+    const postAt = Math.floor(Date.parse(when) / 1000);
+
+    const result = await sendMessage({
+      ctx,
+      targetInput: "C12345678",
+      text: "later",
+      options: { schedule: when },
+    });
+
+    expect(calls).toEqual([
+      {
+        method: "chat.scheduleMessage",
+        params: {
+          channel: "C12345678",
+          text: "later",
+          post_at: postAt,
+          thread_ts: undefined,
+        },
+      },
+    ]);
+    expect(result).toEqual({
+      ok: true,
+      channel_id: "C12345678",
+      scheduled_message_id: "Q1234ABCD",
+      post_at: postAt,
+      thread_ts: undefined,
+    });
+  });
+
+  test("--schedule-in computes a relative post_at", async () => {
+    const calls: { method: string; params: Record<string, unknown> }[] = [];
+    const ctx = createContext(calls);
+    const before = Math.floor(Date.now() / 1000);
+
+    await sendMessage({
+      ctx,
+      targetInput: "C12345678",
+      text: "later",
+      options: { scheduleIn: "3h" },
+    });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.method).toBe("chat.scheduleMessage");
+    expect(calls[0]?.params.post_at as number).toBeGreaterThanOrEqual(before + 3 * 3600 - 1);
+    expect(calls[0]?.params.post_at as number).toBeLessThanOrEqual(before + 3 * 3600 + 1);
+  });
+
+  test("--schedule composes with blocks, thread replies, and reply broadcast", async () => {
+    const calls: { method: string; params: Record<string, unknown> }[] = [];
+    const ctx = createContext(calls);
+    const dir = await mkdtemp(join(tmpdir(), "agent-slack-send-test-"));
+    const blocksPath = join(dir, "blocks.json");
+    const blocks = [{ type: "section", text: { type: "mrkdwn", text: "summary" } }];
+    await writeFile(blocksPath, JSON.stringify(blocks));
+
+    try {
+      await sendMessage({
+        ctx,
+        targetInput: "C12345678",
+        text: "fallback",
+        options: {
+          blocks: blocksPath,
+          threadTs: "1770160000.000001",
+          replyBroadcast: true,
+          scheduleIn: "30m",
+        },
+      });
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.method).toBe("chat.scheduleMessage");
+    expect(calls[0]?.params).toMatchObject({
+      channel: "C12345678",
+      text: "fallback",
+      thread_ts: "1770160000.000001",
+      blocks,
+      reply_broadcast: true,
+    });
+  });
+
+  test("--schedule cannot be combined with file attachments", async () => {
+    const calls: { method: string; params: Record<string, unknown> }[] = [];
+    const ctx = createContext(calls);
+
+    await expect(
+      sendMessage({
+        ctx,
+        targetInput: "C12345678",
+        text: "later with file",
+        options: { attach: ["./report.md"], scheduleIn: "1h" },
+      }),
+    ).rejects.toThrow(/cannot be combined with --attach/);
+
+    expect(calls).toHaveLength(0);
+  });
+});
+
+describe("scheduled message management", () => {
+  test("lists scheduled messages and forwards channel filters", async () => {
+    const calls: { method: string; params: Record<string, unknown> }[] = [];
+    const ctx = createContext(calls);
+
+    const result = await listScheduledMessages({
+      ctx,
+      options: {
+        channel: "general",
+        cursor: "cursor-1",
+        oldest: "1770160000",
+        latest: "1770170000",
+        limit: "25",
+      },
+    });
+
+    const listCall = calls.find((c) => c.method === "chat.scheduledMessages.list");
+    expect(listCall?.params).toEqual({
+      channel: "C12345678",
+      cursor: "cursor-1",
+      oldest: "1770160000",
+      latest: "1770170000",
+      limit: 25,
+    });
+    expect(result).toEqual({
+      ok: true,
+      scheduled_messages: [
+        {
+          id: "Q1234ABCD",
+          channel_id: "C12345678",
+          post_at: 1770168709,
+          text: "scheduled",
+        },
+      ],
+      next_cursor: "next-1",
+    });
+  });
+
+  test("cancels scheduled messages with the required channel id", async () => {
+    const calls: { method: string; params: Record<string, unknown> }[] = [];
+    const ctx = createContext(calls);
+
+    const result = await cancelScheduledMessage({
+      ctx,
+      scheduledMessageId: "Q1234ABCD",
+      options: { channel: "C12345678" },
+    });
+
+    expect(calls).toEqual([
+      {
+        method: "chat.deleteScheduledMessage",
+        params: { channel: "C12345678", scheduled_message_id: "Q1234ABCD" },
+      },
+    ]);
+    expect(result).toEqual({
+      ok: true,
+      channel_id: "C12345678",
+      scheduled_message_id: "Q1234ABCD",
+    });
+  });
+});
+
+describe("scheduled message time parsing", () => {
+  test("parses absolute ISO timestamps with explicit timezones", () => {
+    expect(parseAbsoluteSchedule("2026-06-15T18:00:00-07:00")).toBe(
+      Math.floor(Date.parse("2026-06-15T18:00:00-07:00") / 1000),
+    );
+    expect(() => parseAbsoluteSchedule("2026-06-15T18:00:00")).toThrow(/explicit timezone/);
+  });
+
+  test("parses named relative times like monday 9am", () => {
+    const now = new Date(2026, 4, 30, 12, 0, 0, 0);
+    const result = parseRelativeSchedule("monday 9am", { now });
+    const expected = new Date(now);
+    expected.setDate(now.getDate() + 2);
+    expected.setHours(9, 0, 0, 0);
+    expect(result).toBe(Math.floor(expected.getTime() / 1000));
+  });
+
+  test("rejects schedule times beyond Slack's 120 day limit", () => {
+    const now = new Date(2026, 4, 30, 12, 0, 0, 0);
+    const tooFar = new Date(now);
+    tooFar.setDate(now.getDate() + 121);
+    expect(() => resolveSchedulePostAt({ schedule: tooFar.toISOString() }, { now })).toThrow(
+      /120 days/,
+    );
+  });
 });
 
 describe("editMessage", () => {