agent-discord

Agent Discord

AI エージェントと人間が、シンプルなコマンドインターフェースを通じて Discord サーバーを利用できるようにする TypeScript 製の CLI ツールです。Discord デスクトップアプリからシームレスにトークンを抽出し（利用できない場合はブラウザーにフォールバック）、複数のサーバーをサポートします。

クイックスタート

# Get server snapshot (credentials are extracted automatically)
agent-discord snapshot

# Send a message
agent-discord message send <channel-id> "Hello from AI agent!"

# List channels
agent-discord channel list

認証

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

macOS では、初回に Keychain のパスワードを求めるプロンプトが表示される場合があります（Discord が保存したトークンの復号に必要です）。このプロンプトが表示されるのは一度だけです。

トークンの取得方法 — 次の 2 つの方法があります。

• agent-discord auth qr — 推奨：Discord モバイルアプリで QR コードをスキャンしてサインインします（Settings → Scan QR Code）。これは最も安全で信頼性の高い方法です。ディスク上の認証情報を読み取るのではなく、Discord 公式の Remote Auth フローを通じて認証するため、デスクトップアプリもブラウザーも必要ありません。スキャンにはスマートフォンが必要なため、ヘッドレスでは実行できません。
• agent-discord auth extract：まず Discord デスクトップアプリからトークンを抽出し、アプリがインストールされていない場合は Chromium ブラウザーにフォールバックします。スキャンに使うスマートフォンがない場合の、自動化やヘッドレス環境での利用に最適です。

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

# Generate a QR code and wait for you to scan it with the Discord mobile app
agent-discord auth qr

# Show protocol details while debugging
agent-discord auth qr --debug

Discord モバイルアプリを開き、Settings → Scan QR Code を選択して、表示されたコードをスキャンし、スマートフォンで確定します。トークン（および検出されたすべてのサーバー）は、auth extract と同様に検証され、保存されます。QR コードの有効期限は約 150 秒です。新しいコードを生成するには、コマンドを再実行してください。フローの詳細については、references/authentication.md を参照してください。

複数サーバーのサポート

# List all available servers
agent-discord server list

# Switch to a different server
agent-discord server switch <server-id>

# Show current server
agent-discord server current

# Check auth status
agent-discord auth status

メモリ

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

メモリの読み込み

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

• ファイルがまだ存在しない場合は問題ありません。そのまま作業を進め、有用な情報を初めて保存するときに作成してください。
• ファイルを読み込めない場合（権限やディレクトリがない場合など）は、メモリなしで作業を進めてください。エラーにする必要はありません。

メモリの書き込み

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

• サーバー ID と名前を見つけた後（server list、snapshot などから）
• 有用なチャンネル ID と名前を見つけた後（channel list、snapshot などから）
• ユーザー ID と名前を見つけた後（user list、user me などから）
• ユーザーから別名や設定を伝えられた後（「これを開発サーバーと呼んで」「メインのチャンネルは X」など）
• チャンネル構成を見つけた後（カテゴリー、ボイスチャンネルなど）

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

保存する情報

• サーバー ID と名前
• チャンネル ID、名前、カテゴリー
• ユーザー ID と表示名
• ユーザーが指定した別名（「開発サーバー」「お知らせチャンネル」など）
• よく使うスレッド ID
• やり取りの中で示されたユーザーの設定

保存してはいけない情報

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

古くなったデータの扱い

記憶した ID がエラーを返す場合（チャンネルが見つからない、サーバーが見つからないなど）は、MEMORY.md から削除してください。記憶したデータを盲信せず、違和感がある場合は確認してください。古くなっている可能性のある ID を使うより、一覧を再取得してください。

形式／例

# Agent Messenger Memory

## Discord Servers

- `1234567890123456` — Acme Dev (default)
- `9876543210987654` — Open Source Community

## Channels (Acme Dev)

- `1111111111111111` — #general (General category)
- `2222222222222222` — #engineering (Engineering category)
- `3333333333333333` — #deploys (Engineering category)

## Users (Acme Dev)

- `4444444444444444` — Alice (server owner)
- `5555555555555555` — Bob

## Aliases

- "dev server" → `1234567890123456` (Acme Dev)
- "deploys" → `3333333333333333` (#deploys in Acme Dev)

## Notes

- User prefers --pretty output for snapshots
- Main server is "Acme Dev"

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

コマンド

認証コマンド

# Extract token from Discord desktop app or browser (usually automatic)
agent-discord auth extract
agent-discord auth extract --debug
agent-discord auth extract --browser-profile ~/browser-data
agent-discord auth extract --browser-profile "$HOME/work-profile,$HOME/personal-profile"

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

# Sign in by scanning a QR code with the Discord mobile app (Settings -> Scan QR Code)
agent-discord auth qr
agent-discord auth qr --debug

# Check auth status
agent-discord auth status

# Logout from Discord
agent-discord auth logout

Whoami コマンド

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

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

メッセージコマンド

# Send a message
agent-discord message send <channel-id> <content>
agent-discord message send 1234567890123456789 "Hello world"

# List messages
agent-discord message list <channel-id>
agent-discord message list 1234567890123456789 --limit 50

# Get a single message by ID
agent-discord message get <channel-id> <message-id>
agent-discord message get 1234567890123456789 9876543210987654321

# Edit a message
agent-discord message edit <channel-id> <message-id> <content>
agent-discord message edit 1234567890123456789 9876543210987654321 "Updated text"

# Delete a message
agent-discord message delete <channel-id> <message-id> --force

# Acknowledge/mark a message as read
agent-discord message ack <channel-id> <message-id>

# Search messages in current server
agent-discord message search <query>
agent-discord message search "project update" --limit 10
agent-discord message search "hello" --channel <channel-id> --author <user-id>

チャンネルコマンド

# List channels in current server
# Includes text, announcement, voice/stage (voice channels carry text chat),
# forum, media, and directory channels. Categories and threads are excluded.
agent-discord channel list

# Get channel info
agent-discord channel info <channel-id>
agent-discord channel info 1234567890123456789

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

サーバーコマンド

# List all servers
agent-discord server list

# Get server info
agent-discord server info <server-id>

# Switch active server
agent-discord server switch <server-id>

# Show current server
agent-discord server current

server info は、ブーストティア、カスタム絵文字とスタンプの数、 およびそのティアで残っている空き枠も報告します。

ユーザーコマンド

# List server members
agent-discord user list

# Get user info
agent-discord user info <user-id>

# Get current user
agent-discord user me

DM コマンド

# List DM channels
agent-discord dm list

# Create a DM channel with a user
agent-discord dm create <user-id>

# List unread DM and group-DM channels, newest first
agent-discord dm unread
agent-discord dm unread --limit 10

dm unread は、mention unread では確認できない内容を対象とします。Discord のメンション履歴に記録されるのは サーバー内のメンションだけなので、未読メッセージがいくつあっても、通常の DM はそこには表示されません。代わりに、各 DM チャンネルの last_message_id と既読マーカーを比較します。

unread_count は Discord 独自のバッジカウンターで、DM ではメンションだけでなくすべてのメッセージを数えます。チャンネルに既読状態のエントリがない場合は null（件数不明）です （メッセージがあり、マーカーのない DM は、既読よりも未開封の可能性が高いため、チャンネルは引き続き報告されます）。DM がミュートされていて、実際に未読の場合は 0 です。count と total_unread は見つかったすべての未読 DM を表すため、--limit で返されるリストが制限されても 正確な値が保たれます。total_unread は、判明している件数のみを合計します。

Discord から部分的な既読状態が届いた場合、complete は false です。既読状態の エントリがないことを「未開封」とみなせるのは、コレクションが完全な場合だけです。そのため、部分的なペイロードでは該当チャンネルは省略され、リストが短くなることがあります。

このコマンドは短時間のゲートウェイ接続を開くことに注意してください。Discord はゲートウェイの READY ペイロードを通じてのみ既読状態を公開するためです。 dm list とは異なり、数秒かかることがあります。

メンションコマンド

# List recent mentions
agent-discord mention list
agent-discord mention list --limit 50
agent-discord mention list --guild <server-id>

# List only unread mentions (the app's unread-mention badge)
agent-discord mention unread
agent-discord mention unread --guild <server-id>
agent-discord mention unread --limit 200

mention unread は、直近のメンション履歴（過去 7 日間）を Discord の チャンネルごとの既読状態と照合し、各チャンネルの既読マーカーより新しいメンションのみを返します。出力には、count（列挙された未読メンション数）、badge_count（Discord 独自の アカウント全体の未読メンションバッジ数。--guild では絞り込まれません）、および complete（7 日間の履歴を最後までスキャンできたかどうか）が含まれます。7 日間の期間外に未読メンションがある場合、badge_count は count を上回ることがあります。

フレンドコマンド

# List all relationships (friends, blocked, pending requests)
agent-discord friend list
agent-discord friend list --pretty

ノートコマンド

# Get note for a user
agent-discord note get <user-id>

# Set note for a user
agent-discord note set <user-id> "Note content"

プロフィールコマンド

# Get detailed user profile
agent-discord profile get <user-id>

メンバーコマンド

# Search guild members
agent-discord member search <guild-id> <query>
agent-discord member search 1234567890123456789 "john" --limit 20

# Get your own membership and roles in a guild
agent-discord member me
agent-discord member me 1234567890123456789

スレッドコマンド

# Create a thread in a channel
agent-discord thread create <channel-id> <name>
agent-discord thread create 1234567890123456789 "Discussion" --auto-archive-duration 1440

# Archive a thread
agent-discord thread archive <thread-id>

リアクションコマンド

# Add reaction (use emoji name without colons)
agent-discord reaction add <channel-id> <message-id> <emoji>
agent-discord reaction add 1234567890123456789 9876543210987654321 thumbsup

# Remove reaction
agent-discord reaction remove <channel-id> <message-id> <emoji>

# List reactions on a message
agent-discord reaction list <channel-id> <message-id>

ファイルコマンド

# Upload file
agent-discord file upload <channel-id> <path>
agent-discord file upload 1234567890123456789 ./report.pdf

# List files in channel
agent-discord file list <channel-id>

# Get file info
agent-discord file info <channel-id> <file-id>

絵文字コマンド

作成には CREATE_GUILD_EXPRESSIONS が必要です。他のユーザーのエクスプレッションを削除するには MANAGE_GUILD_EXPRESSIONS が必要ですが、一覧表示にはどちらも不要です。名前に使用できるのは、英字、数字、 アンダースコアのみで、2～32 文字です。画像は最大 256KB です。

# List custom emoji
agent-discord emoji list <server-id>

# Upload (name defaults to the filename without extension)
agent-discord emoji create <server-id> <path>
agent-discord emoji create 1234567890123456789 ./potato.png --name potato

# Delete
agent-discord emoji delete <server-id> <emoji-id>

スタンプコマンド

絵文字と同じ権限が必要です。PNG、APNG、GIF、または Lottie JSON に対応し、最大 512KB です。名前は 2～30 文字です。Lottie を使用するには、ギルドが VERIFIED または PARTNERED である必要があります。Discord の ドキュメントでは 320x320 とされていますが、408x408 の PNG も受け付けられたため、CLI では サイズを検証しません。拡張子ではなくファイルのバイト列から形式を確認します。

# List custom stickers
agent-discord sticker list <server-id>

# Upload — --tags is the unicode emoji the sticker relates to
agent-discord sticker create <server-id> <path> --tags <emoji>
agent-discord sticker create 1234567890123456789 ./potato.png --tags 🥔 --name potato

# Delete
agent-discord sticker delete <server-id> <sticker-id>

メディアタイプは拡張子ではなくファイルのバイト列から読み取られ、各コマンドで受け付ける形式はエンドポイントによって異なります。絵文字では PNG、GIF、JPEG、WebP が使用でき、 スタンプでは PNG、APNG、GIF、および Lottie 用の JSON ドキュメントが使用できます。それ以外の形式はリクエスト送信前にローカルで名前付きエラーとなるため、バッチ処理では 単に Invalid Asset が返されるのではなく、どのファイルに問題があったかが示されます。

バッチアップロードの前に、残りの枠を確認してください。agent-discord server info <server-id> は、ブーストティア、各種数、空き枠を報告します。Discord ではブーストレベルに応じて、両方の上限が増加します。ティア 0～3 の静的絵文字数は 50/100/150/250、スタンプ数は 5/15/30/60 です。

Snapshot コマンド

AI エージェント向けにサーバーの概要を取得します（デフォルトは簡易表示です）。

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

# Full snapshot — includes messages and members (slow, large output)
agent-discord snapshot --full

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

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

デフォルトでは、次の内容を含む簡易 JSON を返します。

• サーバーのメタデータ（id、name）
• チャンネル（id、name） — 一覧表示可能なすべてのチャンネル（テキスト、アナウンス、ボイス／ステージ、フォーラム、メディア、ディレクトリ。カテゴリーとスレッドは除く）
• 次のコマンドのヒント

一覧に表示されるすべてのチャンネルで、message list を直接実行できるとは限りません。フォーラム、メディア、ディレクトリのチャンネルはコンテナーまたはハブビューであり、直接表示できるメッセージのタイムラインはありません。メッセージは子投稿／スレッドにあります。message list には、テキスト、アナウンス、ボイス、またはステージのチャンネルを使用してください。

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

• サーバーのメタデータ（id、name）
• チャンネル（id、name、type、topic）
• 最近のメッセージ（id、content、author、timestamp）
• メンバー（id、username、global_name）

出力形式

JSON（デフォルト）

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

{
  "id": "1234567890123456789",
  "content": "Hello world",
  "author": "username",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

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

--pretty フラグを指定すると、整形された出力を使用できます。

agent-discord channel list --pretty

Slack との主な違い

機能	Discord	Slack
サーバーの用語	サーバー	ワークスペース
チャンネル識別子	Snowflake ID	チャンネル名または ID
メッセージ識別子	Snowflake ID	タイムスタンプ（ts）
スレッド	スレッド ID フィールド	スレッドのタイムスタンプ
メンション	<@user_id>	<@USER_ID>

重要：Discord では、すべての識別子に Snowflake ID（1234567890123456789 のような大きな数値）を使用します。チャンネル名を直接指定することはできません。まず channel list を使って ID を確認してください。

よくあるパターン

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

テンプレート

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

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

エラー処理

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

{
  "error": "Not authenticated. Run \"auth extract\" first."
}

よくあるエラー：

• Not authenticated：有効なトークンがありません（自動抽出に失敗しました。サインインするには auth qr を実行するか、「トラブルシューティング」を参照してください）
• No current server set：最初に server switch <id> を実行してください
• Message not found：メッセージ ID が無効です
• Unknown Channel：チャンネル ID が無効です
• File is not one of ...：このエンドポイントが受け付ける形式とファイルのバイト列が一致しません。ローカルで拒否されたため、リクエストは送信されていません。再試行しても意味はありません。
• File is a <format>; this endpoint takes ...：実際の画像ファイルですが、このエンドポイントが受け付ける形式ではありません。JPEG または WebP のステッカー、あるいは JSON の絵文字です。形式を変換してください。これもローカルで拒否されます。
• Emoji name may only contain ... / ... name must be at least 2 characters：名前が Discord のルールに違反しているため、ローカルで拒否されました。--name を指定しない場合、名前はファイル名から取得されるため、potato-13.png はハイフンが原因で失敗します。
• JSON file is not a Lottie animation (no layers array) / ... is not valid JSON / ... is not valid UTF-8：アニメーションとして使用できない JSON ステッカーです。layers 配列を含んでいてもファイルが壊れている場合があるため、それぞれ個別に原因が示されます。いずれもローカルで拒否されます。このようなファイルを送信すると、Discord は Invalid Asset だけを返します。
• Invalid Asset（Discord からの応答）：形式はローカルで受け付けられましたが、Discord がコンテンツ自体を拒否しました。画像が途中で切れているか、破損しています。
• Maximum number of stickers reached (N)（Discord からの応答）：空きスロットがありません。一括処理の前に server info でプランの上限を確認してください。

設定

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

SDK：プログラムからの利用

スクリプトや自動化を構築するための TypeScript SDK として DiscordClient を利用できます。

セットアップ

import { DiscordClient } from 'agent-messenger/discord'

const client = await new DiscordClient().login()

または、認証情報を手動で管理する方法：

import { DiscordClient, DiscordCredentialManager } from 'agent-messenger/discord'

const manager = new DiscordCredentialManager()
const token = await manager.getToken()
if (!token) {
  throw new Error('Discord token not found. Run auth extract first.')
}
const client = await new DiscordClient().login({ token })

QR コードログイン（推奨）

loginWithRemoteAuth は、Discord のモバイルアプリで QR コードをスキャンしてサインインします。デスクトップアプリやトークンの抽出は不要です。Discord の Remote Auth プロトコルを実行し、表示用の QR URL を渡します。ユーザーがスマートフォンでスキャンして確認すると、ユーザートークンを受け取ります。

import { DiscordClient, loginWithRemoteAuth } from 'agent-messenger/discord'

const session = await loginWithRemoteAuth({
  onQrUrl: (url) => {
    // Render this URL as a QR code (e.g. with the `qrcode` package)
    console.log('Scan this with the Discord mobile app:', url)
  },
})

const client = await new DiscordClient().login({ token: session.token })

session は { token, user } です。ゲートウェイがユーザーペイロードを省略した場合、user は null になることがあります。ID が必要な場合は、ログイン後に await client.testAuth() を呼び出してください。Discord が最終トークン交換時に CAPTCHA を要求した場合、この呼び出しはコード remote_auth_captcha の DiscordError で拒否されます。その場合は auth extract にフォールバックしてください。Discord アプリをインストールしたスマートフォンが必要なため、ヘッドレス環境では実行できません。

例

// Send a message
const msg = await client.sendMessage(channelId, 'Hello from SDK!')

// React to it
await client.addReaction(channelId, msg.id, '👋')

// Search messages
const { results } = await client.searchMessages(serverId, 'deployment', {
  sortBy: 'timestamp',
  sortOrder: 'desc',
  limit: 5,
})

// Get your own membership and the server's role definitions
const member = await client.getMyGuildMember(serverId)
const roles = await client.listRoles(serverId)

// List unread mentions (correlates mention history with per-channel read state)
const { mentions, count, badgeCount, complete } = await client.getUnreadMentions()
// count = enumerated unread mentions; badgeCount = account-wide badge total;
// complete = true when all available mentions (7-day window) were scanned,
// false when the scan stopped early at the limit or a non-advancing cursor

// Create a thread
const thread = await client.createThread(channelId, 'Discussion Topic')
await client.sendMessage(thread.id, 'First message in thread')

リアルタイムイベント（SDK）

DiscordListener は Discord の Gateway WebSocket に接続し、イベントをリアルタイムでストリーミングします。

import { DiscordClient, DiscordListener } from 'agent-messenger/discord'

const client = await new DiscordClient().login()
const listener = new DiscordListener(client)

listener.on('message_create', (event) => {
  console.log(`${event.author.username}: ${event.content}`)
})

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

await listener.start()
// listener.stop()

利用可能なイベント：message_create、message_update、message_delete、message_reaction_add、message_reaction_remove、guild_member_add、guild_member_remove、typing_start、presence_update、channel_create、channel_update、channel_delete、discord_event（すべてのイベントを捕捉）、connected、disconnected、error。

注：MessageContent、GuildMembers、GuildPresences は特権インテントです。options.intents で明示的に渡してください。

API リファレンス全編

メソッドシグネチャ、型、スキーマ、例の全容については、Discord SDK documentation をご覧ください。

制限事項

• 音声オーディオには対応していません（ボイス／ステージチャンネルの一覧表示と、埋め込みテキストチャットの閲覧はできますが、ボイスへの参加や音声のストリーミングには対応していません）
• サーバー管理には対応していません（チャンネルやロールの作成・削除）
• スラッシュコマンドには対応していません
• Webhook には対応していません
• プレーンテキストメッセージのみ対応しています（v1 では埋め込みに対応していません）
• ユーザートークンのみ対応しています（ボットトークンには対応していません）

トラブルシューティング

agent-discord: command not found

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

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

agent-discord server list

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

npx -y agent-messenger discord server list
bunx agent-messenger discord server list
pnpm dlx agent-messenger discord server list

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

npx agent-discord、bunx agent-discord、pnpm dlx agent-discord は絶対に実行しないでください。agent-discord は npm パッケージ名ではないため、失敗するか、誤ったパッケージがインストールされます。

認証情報の抽出、トークンの問題、権限など、その他のトラブルシューティングについては、references/authentication.md をご覧ください。

リファレンス

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