agent-slack

Agent Slack

AI エージェントと人間が、シンプルなコマンドインターフェースを通じて Slack ワークスペースを操作できる TypeScript CLI ツールです。Slack デスクトップアプリからトークンをシームレスに抽出する機能（ブラウザーへのフォールバックあり）と、複数ワークスペースのサポートを備えています。

クイックスタート

# Get workspace snapshot (credentials are extracted automatically)
agent-slack snapshot

# Send a message
agent-slack message send general "Hello from AI agent!"

# List channels
agent-slack channel list

認証

初回使用時に、Slack デスクトップアプリ（またはフォールバックとして Chromium ブラウザー）から認証情報が自動的に抽出されます。手動での設定は不要です。任意のコマンドを実行するだけで、バックグラウンドで認証が自動的に行われます。

macOS では、初回にシステムからキーチェーンのパスワードを求められる場合があります（Slack に保存されたトークンの復号に必要です）。この確認は一度だけです。

トークンを取得する方法は 2 つあります：

• agent-slack auth qr — 推奨。 Slack の「モバイル端末でサインイン」画面の QR コードを使ってサインインします。最も安全で信頼性の高い方法です。ディスク上の認証情報を読み取るのではなく、プレーン HTTP 経由で Slack 独自のログインフローを通じて認証され、デスクトップアプリもブラウザーも必要ありません。
• agent-slack auth extract。 最初に Slack デスクトップアプリからトークンを抽出し、アプリがインストールされていない場合は Chromium ブラウザーにフォールバックします。自動化環境やヘッドレス環境に最適です。

QR コードでのサインイン（推奨）

すでに Slack にログインしている任意のデバイスから QR コードを使ってサインインできます。デスクトップアプリもブラウザーの自動操作も不要で、すべて HTTP 経由で行われます：

# In Slack (desktop or web): your name (top-left) → "Sign in on mobile".
# Right-click the QR code → "Copy Image Address", then:
pbpaste | agent-slack auth qr

# Or pass the data URL directly:
agent-slack auth qr "data:image/png;base64,iVBORw0KGgo..."

QR コードの一度限りのログインリンクをデコードし、セッションを確立して、auth extract と同様に認証情報を保存します。QR コードのリンクは一度しか使用できません。期限が切れた場合は、新しいものを生成してください。

複数ワークスペースのサポート

# List all authenticated workspaces
agent-slack workspace list

# Switch to a different workspace
agent-slack workspace switch <workspace-id>

# Show current workspace
agent-slack workspace current

# Remove a workspace
agent-slack workspace remove <workspace-id>

# Check auth status
agent-slack auth status

# Run one command against another workspace without switching
agent-slack --workspace <workspace-id> channel list
agent-slack --workspace <workspace-id> auth status

グローバルな --workspace <id> フラグはコマンドより前に指定し、auth status や auth logout を含む、保存済みのワークスペースを使用するすべてのコマンドに適用されます。このフラグは今回の実行に限って指定したワークスペースを対象にし、現在のワークスペースは変更しません。ID が保存されていない場合、auth status は Workspace not found: <id> で失敗します。auth extract と auth qr は特定のワークスペースを対象にするのではなく、ワークスペースを検出するため、このフラグの影響を受けません。これらのコマンドは、現在のワークスペースがまだ設定されていない場合にのみ、現在のワークスペースを設定します。

メモリ

エージェントは、セッションをまたいで保持されるメモリとして ~/.config/agent-messenger/MEMORY.md ファイルを管理します。このファイルはエージェントが管理するもので、CLI は読み書きしません。Read ツールと Write ツールを使ってメモリファイルを管理してください。

メモリの読み込み

すべてのタスクの開始時に、Read ツールを使って ~/.config/agent-messenger/MEMORY.md を読み込み、以前に見つかったワークスペース ID、チャンネル ID、ユーザー ID、設定を読み込んでください。

• ファイルがまだ存在しない場合は問題ありません。ファイルを使わずに作業を続け、保存する有用な情報が初めて得られたときに作成してください。
• ファイルを読み込めない場合（権限がない、ディレクトリがないなど）は、メモリを使わずに続行してください。エラーにしないでください。

メモリの書き込み

有用な情報を見つけた後、Write ツールを使って ~/.config/agent-messenger/MEMORY.md を更新してください。書き込みが必要になるタイミングは次のとおりです：

• ワークスペース ID を見つけた後（workspace list から）
• 有用なチャンネル ID と名前を見つけた後（channel list、snapshot などから）
• ユーザー ID と名前を見つけた後（user list、user me などから）
• ユーザーから別名や設定を伝えられた後（「これを deploys チャンネルと呼んで」「メインのワークスペースは X」など）
• チャンネル構造を見つけた後（サイドバーのセクション、チャンネルのカテゴリ）

書き込む際は、ファイルの全内容を含めてください。Write ツールはファイル全体を上書きします。

保存する内容

• ワークスペース ID と名前
• チャンネル ID、名前、用途
• ユーザー ID と表示名
• ユーザーが指定した別名（「deploys チャンネル」「メインのワークスペース」）
• よく使うスレッドのタイムスタンプ
• やり取りの中でユーザーが伝えた設定

保存してはいけない内容

トークン、Cookie、認証情報、その他の機密データは決して保存しないでください。メッセージの全文は保存せず（ID とチャンネルのコンテキストのみ保存してください）、ファイルのアップロード内容も保存しないでください。

古いデータの取り扱い

記憶している ID でエラー（チャンネルが見つからない、ユーザーが見つからないなど）が返された場合は、MEMORY.md から削除してください。記憶したデータを盲目的に信頼せず、何かおかしいと感じたら確認してください。古い可能性のある記憶済み ID を使うより、再度一覧を取得してください。

形式／例

# Agent Messenger Memory

## Slack Workspaces

- `T0ABC1234` — Acme Corp (default)
- `T0DEF5678` — Side Project

## Channels (Acme Corp)

- `C012ABC` — #general (company-wide announcements)
- `C034DEF` — #engineering (team discussion)
- `C056GHI` — #deploys (CI/CD notifications)

## Users (Acme Corp)

- `U0ABC123` — Alice (engineering lead)
- `U0DEF456` — Bob (backend)

## Aliases

- "deploys" → `C056GHI` (#deploys in Acme Corp)
- "main workspace" → `T0ABC1234` (Acme Corp)

## Notes

- User prefers --pretty output for snapshots
- Main workspace is "Acme Corp"

メモリを使うと、channel list と workspace list の呼び出しを繰り返さずに済みます。前のセッションで ID が分かっている場合は、その ID を直接使ってください。

コマンド

認証コマンド

# Extract tokens from Slack desktop app or browser (usually automatic)
agent-slack auth extract
agent-slack auth extract --debug
agent-slack auth extract --browser-profile ~/browser-data
agent-slack auth extract --browser-profile ~/work-profile --browser-profile ~/personal-profile

# --browser-profile accepts repeatable or comma-separated Chromium profile/user-data dirs

# Sign in with a QR code from Slack's "Sign in on mobile" screen (no desktop app needed)
agent-slack auth qr "data:image/png;base64,..."
pbpaste | agent-slack auth qr
agent-slack auth qr --debug   # show each redirect hop for troubleshooting

# Check auth status
agent-slack auth status

# Logout from a workspace (defaults to the --workspace selection, then current)
agent-slack auth logout
agent-slack auth logout <workspace-id>
agent-slack --workspace <workspace-id> auth logout

Whoami コマンド

# Show current authenticated user
agent-slack whoami
agent-slack whoami --pretty

出力には、認証済みユーザーの ID 情報が含まれます。

メッセージコマンド

# Send a message
agent-slack message send <channel> <text>
agent-slack message send general "Hello world"

# Send a threaded reply
agent-slack message send general "Reply" --thread <ts>

# List messages
agent-slack message list <channel>
agent-slack message list general --limit 50

# Search messages across workspace
agent-slack message search <query>
agent-slack message search "project update"
agent-slack message search "from:@user deadline" --limit 50
agent-slack message search "in:#general meeting" --sort timestamp

# Get a single message by timestamp
agent-slack message get <channel> <ts>
agent-slack message get general 1234567890.123456

# Get thread replies (includes parent message)
agent-slack message replies <channel> <thread_ts>
agent-slack message replies general 1234567890.123456
agent-slack message replies general 1234567890.123456 --limit 50
agent-slack message replies general 1234567890.123456 --oldest 1234567890.000000
agent-slack message replies general 1234567890.123456 --cursor <next_cursor>

# Edit a message
agent-slack message edit <channel> <ts> <new-text>

# Delete a message
agent-slack message delete <channel> <ts> --force

# Schedule a message (post_at is a Unix timestamp)
agent-slack message schedule <channel> <text> <post-at>
agent-slack message schedule general "Friday update" 1700000000
agent-slack message schedule general "Thread reply" 1700000000 --thread 1234567890.123456

# List scheduled messages
agent-slack message scheduled-list
agent-slack message scheduled-list --channel general

# Delete a scheduled message
agent-slack message scheduled-delete <channel> <scheduled-message-id>

# Post ephemeral message (visible only to a specific user)
agent-slack message ephemeral <channel> <user-id> <text>

# Get a permanent link to a message
agent-slack message permalink <channel> <ts>

チャンネルコマンド

# List channels (excludes archived by default)
agent-slack channel list
agent-slack channel list --type public
agent-slack channel list --type private
agent-slack channel list --type dm
agent-slack channel list --include-archived

# Get channel info
agent-slack channel info <channel>
agent-slack channel info general

# Get channel history (alias for message list)
agent-slack channel history <channel> --limit 100

# Open a DM channel with a user (returns channel ID)
agent-slack channel open <user_id>
agent-slack channel open U0ABC123

# Open a group DM with multiple users
agent-slack channel open U0ABC123,U0DEF456

# List users in a channel
agent-slack channel users <channel>
agent-slack channel users general --include-bots

# Create a new channel
agent-slack channel create <name>
agent-slack channel create my-new-channel --private

# Archive a channel
agent-slack channel archive <channel>

# Set channel topic
agent-slack channel set-topic <channel> <topic>

# Set channel purpose
agent-slack channel set-purpose <channel> <purpose>

# Invite users to a channel (comma-separated user IDs)
agent-slack channel invite <channel> <users>
agent-slack channel invite general U0ABC123,U0DEF456

# Join a channel
agent-slack channel join <channel>

# Leave a channel
agent-slack channel leave <channel>

ユーザーコマンド

# List users
agent-slack user list
agent-slack user list --include-bots

# Get user info
agent-slack user info <user>

# Get current user
agent-slack user me

# Look up user by email
agent-slack user lookup <email>
agent-slack user lookup [email protected] --pretty

# Get detailed user profile
agent-slack user profile <user-id>

# Set your status (emoji name without colons)
agent-slack user set-status <status-text>
agent-slack user set-status "In a meeting" --emoji calendar
agent-slack user set-status "On vacation" --emoji palm_tree --expiration 1700100000

リアクションコマンド

# Add reaction
agent-slack reaction add <channel> <ts> <emoji>
agent-slack reaction add general 1234567890.123456 thumbsup

# Remove reaction
agent-slack reaction remove <channel> <ts> <emoji>

# List reactions on a message
agent-slack reaction list <channel> <ts>

ファイルコマンド

# Upload file(s)
agent-slack file upload <channel> <path...>
agent-slack file upload general ./report.pdf

# Upload into a thread with a comment (files grouped into one message)
agent-slack file upload general ./shot.png --thread 1700000000.000100 --comment "triage notes"
agent-slack file upload general ./a.png ./b.png --thread 1700000000.000100 --title "screenshots"

# --filename overrides the name (single file only); output is an object for one file, an array for several
agent-slack file upload general ./report.pdf --filename q3-report.pdf

# List files
agent-slack file list
agent-slack file list --channel general

# Get file info
agent-slack file info <file-id>

# Download file
agent-slack file download <file-id>
agent-slack file download <file-id> [output-path]
agent-slack file download F0ABC123 ./downloads/

# Delete a file
agent-slack file delete <file-id>

未読コマンド

# Get unread counts for all channels
agent-slack unread counts

# Get thread subscription details
agent-slack unread threads <channel> <thread_ts>

# Mark channel as read up to timestamp
agent-slack unread mark <channel> <ts>

アクティビティコマンド

# List activity feed (mentions, reactions, replies)
agent-slack activity list
agent-slack activity list --limit 50
agent-slack activity list --unread
agent-slack activity list --types thread_reply,message_reaction

保存済みアイテムコマンド

# List saved items
agent-slack saved list
agent-slack saved list --limit 10
agent-slack saved list --cursor <next_cursor>

下書きコマンド

# List all drafts
agent-slack drafts list
agent-slack drafts list --limit 10
agent-slack drafts list --cursor <next_cursor>

チャンネルセクションコマンド

# List channel sections (sidebar organization)
agent-slack sections list
agent-slack sections list --pretty

ピン留めコマンド

# Pin a message
agent-slack pin add <channel> <ts>

# Unpin a message
agent-slack pin remove <channel> <ts>

# List pinned messages in a channel
agent-slack pin list <channel>
agent-slack pin list general --pretty

ブックマークコマンド

# Add a bookmark to a channel
agent-slack bookmark add <channel> <title> <link>
agent-slack bookmark add general "Our Docs" https://docs.example.com --emoji books --type link

# Edit a bookmark
agent-slack bookmark edit <channel> <bookmark-id> --title "New Title"
agent-slack bookmark edit <channel> <bookmark-id> --link https://new.example.com

# Remove a bookmark
agent-slack bookmark remove <channel> <bookmark-id>

# List bookmarks in a channel
agent-slack bookmark list <channel>
agent-slack bookmark list general --pretty

リマインダーコマンド

# Add a reminder (time is a Unix timestamp)
agent-slack reminder add "Review PR" 1700000000
agent-slack reminder add "Team standup" 1700000000 --user U0ABC123

# List all reminders
agent-slack reminder list
agent-slack reminder list --pretty

# Complete a reminder
agent-slack reminder complete <reminder-id>

# Delete a reminder
agent-slack reminder delete <reminder-id>

ユーザーグループコマンド

# List all user groups
agent-slack usergroup list
agent-slack usergroup list --include-disabled
agent-slack usergroup list --include-users --pretty

# Create a user group
agent-slack usergroup create "Marketing Team"
agent-slack usergroup create "Marketing Team" --handle marketing-team --description "Marketing gurus"
agent-slack usergroup create "Engineering" --channels C012ABC,C034DEF

# Update a user group (name, handle, description, channels)
agent-slack usergroup update <usergroup-id> --name "New Name"
agent-slack usergroup update S0616NG6M --handle new-handle --description "Updated description"
agent-slack usergroup update S0616NG6M --channels C012ABC,C034DEF

# Enable a disabled user group
agent-slack usergroup enable <usergroup-id>

# Disable a user group
agent-slack usergroup disable <usergroup-id>

# List members of a user group
agent-slack usergroup members <usergroup-id>
agent-slack usergroup members S0616NG6M --include-disabled --pretty

# Update members of a user group (replaces all members)
agent-slack usergroup members-update <usergroup-id> <comma-separated-user-ids>
agent-slack usergroup members-update S0616NG6M U060R4BJ4,U060RNRCZ

絵文字コマンド

# List all custom emoji in the workspace
agent-slack emoji list
agent-slack emoji list --pretty

スナップショットコマンド

AI エージェント向けにワークスペースの概要を取得します（デフォルトでは簡潔な内容）。

# Brief snapshot (default) — fast, minimal API calls
agent-slack snapshot

# Full snapshot — includes messages, users, user groups (slow, large output)
agent-slack snapshot --full

# Filtered full snapshots
agent-slack snapshot --full --channels-only
agent-slack snapshot --full --users-only

# Limit messages per channel (only with --full)
agent-slack snapshot --full --limit 10

デフォルトでは、次の内容を含む簡潔な JSON が返されます。

• ワークスペースのメタデータ
• チャンネル（id、name）— アーカイブされていないもののみ
• 次のコマンドのヒント

--full を指定すると、次の内容を含む包括的な JSON が返されます。

• ワークスペースのメタデータ
• チャンネル（id、name、topic、purpose、is_private、is_archived）
• 最近のメッセージ（ts、text、user、channel）
• ユーザー（id、name、profile）
• ユーザーグループ（id、name、handle、description、user_count、users）

出力形式

JSON（デフォルト）

すべてのコマンドは、AI による利用を想定してデフォルトで JSON を出力します。

{
  "ts": "1234567890.123456",
  "text": "Hello world",
  "channel": "C123456"
}

Pretty（人間が読みやすい形式）

整形された出力には、--pretty フラグを使用してください。

agent-slack channel list --pretty

よく使うパターン

一般的な AI エージェントのワークフローについては、references/common-patterns.md を参照してください。

テンプレート

実行可能な例については、templates/ ディレクトリを参照してください。

• post-message.sh - エラー処理付きでメッセージを送信します
• monitor-channel.sh - チャンネルを監視して新しいメッセージを確認します
• workspace-summary.sh - ワークスペースの概要を生成します

エラー処理

すべてのコマンドは、一貫した形式でエラーを返します。

{
  "error": "No workspace authenticated. Run: agent-slack auth extract"
}

よくあるエラー：

• NO_WORKSPACE：認証済みのワークスペースがありません（自動抽出に失敗しました — トラブルシューティングを参照）
• SLACK_API_ERROR：Slack API がエラーを返しました
• RATE_LIMIT：Slack のレート制限に達しました（バックオフ付きで自動再試行します）

設定

認証情報は ~/.config/agent-messenger/slack-credentials.json に保存されます（権限は 0600）。形式とセキュリティの詳細については、references/authentication.md を参照してください。

SDK：QR コードログイン

loginWithQr は、Slack の「モバイルでサインイン」QR 画像を、プレーン HTTP 経由で使用可能なセッション（トークン＋Cookie）に変換します。ブラウザーやデスクトップアプリは不要です。

import { loginWithQr, SlackClient, SlackCredentialManager } from 'agent-messenger/slack'

// dataUrl is the QR image as a "data:image/png;base64,..." string
const session = await loginWithQr(dataUrl)

const client = await new SlackClient().login({ token: session.token, cookie: session.cookie })
const { team_id, team } = await client.testAuth()

// Persist for later, like the CLI does
await new SlackCredentialManager().setWorkspace({
  workspace_id: team_id,
  workspace_name: team ?? session.workspace,
  token: session.token,
  cookie: session.cookie,
})

loginWithQr(dataUrl, options) は、オプションの { debug, fetchImpl, maxRedirects, requestConfirmationCode } を受け取ります。qr_session_failed（リンクの有効期限切れ／セッションなし）または qr_token_failed（トークンを取得できない）のコードを持つ SlackError をスローします。ログインせずに QR をデコードするには、{ url, workspace, teamId, userId } を返す decodeSlackQr(dataUrl) を使用してください。

Slack の確認コードを処理する（ワークスペースの 2 要素認証）

一部のワークスペースでは、QR コードでのサインイン時にセッション Cookie が発行される前に、確認コードのページ（メールコード、SMS、TOTP など）が表示されます。この手順を完了するには、requestConfirmationCode を渡してください。このコールバックは、Slack に確認ページが実際に表示された場合にのみ呼び出されます。確認コードを直接受け取らずにセッション Cookie が発行される通常の QR ログインでは、入力を求められません。

import { loginWithQr, type SlackConfirmationChallenge } from 'agent-messenger/slack'

const session = await loginWithQr(dataUrl, {
  requestConfirmationCode: async (challenge: SlackConfirmationChallenge) => {
    // challenge.email is the address Slack sent the code to.
    // challenge.type is the mechanism ("email", "sms", "totp", ...) or null if unknown.
    return await promptUserForCode(challenge)
  },
})

仕様：

• 生のコードを string として返してください。送信前に空白がトリミングされます。
• 空文字列（または空白のみ）を返すと中止されます。loginWithQr は qr_session_failed をスローし、コードは送信されません。
• コードは、QR ペイロードに紐付けられた正確な https://<workspace>.slack.com/login/<qrSecret> エンドポイントに送信されます。別のワークスペースのホストまたは予期しないパス名へのリダイレクトは、コールバックの呼び出し前にフローを拒否します。
• コールバックと email／type フィールドは、debug 出力には表示されません。

SDK：リアルタイムイベント

SlackListener は Slack の RTM WebSocket に接続し、イベントを即時にストリーミングします。ポーリングは不要で、イベントがリアルタイムで届きます。

セットアップ

import { SlackClient, SlackListener } from 'agent-messenger/slack'

const client = await new SlackClient().login()
const listener = new SlackListener(client)

または、認証情報を手動で指定します。

import { SlackClient, SlackListener } from 'agent-messenger/slack'

const client = await new SlackClient().login({ token, cookie })
const listener = new SlackListener(client)

イベントのリッスン

listener.on('connected', (info) => {
  console.log(`Connected as ${info.self.id} on ${info.team.id}`)
})

listener.on('message', (event) => {
  // event.type, event.channel, event.user, event.text, event.ts
})

listener.on('reaction_added', (event) => {
  // event.user, event.reaction, event.item.channel, event.item.ts
})

listener.on('reaction_removed', (event) => {
  // same shape as reaction_added
})

listener.on('member_joined_channel', (event) => {
  // event.user, event.channel
})

listener.on('member_left_channel', (event) => {
  // event.user, event.channel
})

listener.on('user_typing', (event) => {
  // event.user, event.channel
})

listener.on('presence_change', (event) => {
  // event.user, event.presence ('active' | 'away')
})

// Catch-all for any RTM event type
listener.on('slack_event', (event) => {
  // event.type + all fields
})

listener.on('error', (err) => {
  console.error(err.message)
})

listener.on('disconnected', () => {
  // auto-reconnects with exponential backoff
})

ライフサイクル

await listener.start()  // connects via RTM WebSocket
listener.stop()         // clean shutdown

イベントの種類

イベント	説明
message	新しいメッセージ、編集、削除、スレッドへの返信、参加／退出のサブタイプ
reaction_added	メッセージにリアクションが追加された
reaction_removed	メッセージからリアクションが削除された
member_joined_channel	ユーザーがチャンネルに参加した
member_left_channel	ユーザーがチャンネルから退出した
user_typing	ユーザーが入力中
presence_change	ユーザーがアクティブまたは離席中になった
channel_created	新しいチャンネルが作成された
channel_deleted	チャンネルが削除された
channel_rename	チャンネル名が変更された
channel_archive	チャンネルがアーカイブされた
channel_unarchive	チャンネルのアーカイブが解除された
slack_event	すべての RTM イベントを捕捉
connected	WebSocket に接続した
disconnected	WebSocket が切断された（自動再接続）
error	接続または API のエラー

注意事項

• 認証済みユーザー向けのワークスペース内のすべてのイベントを受信します。チャンネルの購読は不要です。
• 指数バックオフ（1 秒 → 最大 30 秒）で自動再接続します。
• 30 秒ごとに Ping／Pong によるキープアライブを行います。
• xoxc ユーザートークンを使用して Slack の RTM API に接続します。

制限事項

• プレーンテキストのメッセージのみ（v1 ではブロック／書式設定は非対応）

トラブルシューティング

agent-slack: command not found

agent-slack は npm パッケージ名ではありません。 npm パッケージ名は agent-messenger です。

パッケージがグローバルにインストールされている場合は、agent-slack を直接使用します。

agent-slack message list general

パッケージがインストールされていない場合は、デフォルトで npx -y を使用してください。どのパッケージランナーを使うか、ユーザーに尋ねないでください。そのまま実行してください。

npx -y agent-messenger slack message list general
bunx agent-messenger slack message list general
pnpm dlx agent-messenger slack message list general

ユーザーが好むパッケージランナー（例：bunx、pnpm dlx）がすでにわかっている場合は、代わりにそれを使用してください。

npx agent-slack、bunx agent-slack、pnpm dlx agent-slack は絶対に実行しないでください。npm には agent-slack という名前の、別の無関係な npm パッケージが存在します。これを実行すると、コマンドの種類が異なり（少なく）、誤ったパッケージが気付かれないままインストールされます。

Failed to read Slack cookies

次のように表示された場合：

{"error":"Failed to read Slack cookies. The Slack app is currently running and locking the cookie database. Quit the Slack app completely and try again."}

認証情報を抽出するには Slack アプリを終了する必要があることをユーザーに伝え、確認を求めてください。ユーザーが同意したら、Slack を終了してコマンドを再試行してください。

その他のトラブルシューティング（認証情報の抽出、トークンの問題、Keychain）については、references/authentication.md を参照してください。

参考資料

• 認証ガイド
• 一般的なパターン