agent-messenger 1.0.0

package/skills/agent-discord/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: agent-discord
+description: Interact with Discord servers - send messages, read channels, manage reactions
+allowed-tools: Bash(agent-discord:*)
+---
+
+# Agent Discord
+
+A TypeScript CLI tool that enables AI agents and humans to interact with Discord servers through a simple command interface. Features seamless token extraction from the Discord desktop app and multi-guild support.
+
+## Quick Start
+
+```bash
+# Extract credentials from Discord desktop app (zero-config)
+agent-discord auth extract
+
+# Get guild snapshot
+agent-discord snapshot
+
+# Send a message
+agent-discord message send <channel-id> "Hello from AI agent!"
+
+# List channels
+agent-discord channel list
+```
+
+## Authentication
+
+### Seamless Token Extraction
+
+agent-discord automatically extracts your Discord credentials from the desktop app:
+
+```bash
+# Just run this - no manual token copying needed
+agent-discord auth extract
+
+# Use --debug for troubleshooting
+agent-discord auth extract --debug
+```
+
+This command:
+- Auto-detects your platform (macOS/Linux/Windows)
+- Extracts user token from Discord desktop app's LevelDB storage
+- Validates token against Discord API before saving
+- Discovers ALL joined guilds (servers)
+- Stores credentials securely in `~/.config/agent-messenger/`
+
+### Multi-Guild Support
+
+```bash
+# List all available guilds
+agent-discord guild list
+
+# Switch to a different guild
+agent-discord guild switch <guild-id>
+
+# Show current guild
+agent-discord guild current
+
+# Check auth status
+agent-discord auth status
+```
+
+## Commands
+
+### Message Commands
+
+```bash
+# 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
+
+# Delete a message
+agent-discord message delete <channel-id> <message-id> --force
+```
+
+### Channel Commands
+
+```bash
+# List channels in current guild (text channels only)
+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
+```
+
+### Guild Commands
+
+```bash
+# List all guilds
+agent-discord guild list
+
+# Get guild info
+agent-discord guild info <guild-id>
+
+# Switch active guild
+agent-discord guild switch <guild-id>
+
+# Show current guild
+agent-discord guild current
+```
+
+### User Commands
+
+```bash
+# List guild members
+agent-discord user list
+
+# Get user info
+agent-discord user info <user-id>
+
+# Get current user
+agent-discord user me
+```
+
+### Reaction Commands
+
+```bash
+# 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>
+```
+
+### File Commands
+
+```bash
+# 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>
+```
+
+### Snapshot Command
+
+Get comprehensive guild state for AI agents:
+
+```bash
+# Full snapshot
+agent-discord snapshot
+
+# Filtered snapshots
+agent-discord snapshot --channels-only
+agent-discord snapshot --users-only
+
+# Limit messages per channel
+agent-discord snapshot --limit 10
+```
+
+Returns JSON with:
+- Guild metadata (id, name)
+- Channels (id, name, type, topic)
+- Recent messages (id, content, author, timestamp)
+- Members (id, username, global_name)
+
+## Output Format
+
+### JSON (Default)
+
+All commands output JSON by default for AI consumption:
+
+```json
+{
+  "id": "1234567890123456789",
+  "content": "Hello world",
+  "author": "username",
+  "timestamp": "2024-01-15T10:30:00.000Z"
+}
+```
+
+### Pretty (Human-Readable)
+
+Use `--pretty` flag for formatted output:
+
+```bash
+agent-discord channel list --pretty
+```
+
+## Key Differences from Slack
+
+| Feature | Discord | Slack |
+|---------|---------|-------|
+| Server terminology | Guild | Workspace |
+| Channel identifiers | Snowflake IDs | Channel name or ID |
+| Message identifiers | Snowflake IDs | Timestamps (ts) |
+| Threads | Thread ID field | Thread timestamp |
+| Mentions | `<@user_id>` | `<@USER_ID>` |
+
+**Important**: Discord uses Snowflake IDs (large numbers like `1234567890123456789`) for all identifiers. You cannot use channel names directly - use `channel list` to find IDs first.
+
+## Common Patterns
+
+See `references/common-patterns.md` for typical AI agent workflows.
+
+## Templates
+
+See `templates/` directory for runnable examples:
+- `post-message.sh` - Send messages with error handling
+- `monitor-channel.sh` - Monitor channel for new messages
+- `guild-summary.sh` - Generate guild summary
+
+## Error Handling
+
+All commands return consistent error format:
+
+```json
+{
+  "error": "Not authenticated. Run \"auth extract\" first."
+}
+```
+
+Common errors:
+- `Not authenticated`: No valid token - run `auth extract`
+- `No current guild set`: Run `guild switch <id>` first
+- `Message not found`: Invalid message ID
+- `Unknown Channel`: Invalid channel ID
+
+## Configuration
+
+Credentials stored in: `~/.config/agent-messenger/discord-credentials.json`
+
+Format:
+```json
+{
+  "token": "user_token_here",
+  "current_guild": "1234567890123456789",
+  "guilds": {
+    "1234567890123456789": {
+      "guild_id": "1234567890123456789",
+      "guild_name": "My Server"
+    }
+  }
+}
+```
+
+**Security**: File permissions set to 0600 (owner read/write only)
+
+## Limitations
+
+- No real-time events / Gateway connection
+- No voice channel support
+- No server management (create/delete channels, roles)
+- No slash commands
+- No webhook support
+- Plain text messages only (no embeds in v1)
+- User tokens only (no bot tokens)
+
+## References
+
+- [Authentication Guide](references/authentication.md)
+- [Common Patterns](references/common-patterns.md)

package/skills/agent-discord/references/authentication.md

@@ -0,0 +1,294 @@
+# Authentication Guide
+
+## Overview
+
+agent-discord uses Discord's user token extracted directly from the Discord desktop application. This provides seamless authentication without manual token management.
+
+## Token Extraction
+
+### Automatic Extraction
+
+The simplest way to authenticate:
+
+```bash
+agent-discord auth extract
+
+# Use --debug for troubleshooting extraction issues
+agent-discord auth extract --debug
+```
+
+This command:
+1. Detects your operating system (macOS, Linux, Windows)
+2. Locates the Discord desktop app data directory
+3. Reads the LevelDB storage containing session data
+4. Extracts user token
+5. Validates token against Discord API before saving
+6. Discovers ALL joined guilds (servers)
+7. Stores credentials securely in `~/.config/agent-messenger/discord-credentials.json`
+
+### Platform-Specific Paths
+
+**macOS:**
+```
+~/Library/Application Support/discord/
+```
+
+**Linux:**
+```
+~/.config/discord/
+```
+
+**Windows:**
+```
+%APPDATA%\discord\
+```
+
+The tool searches within:
+- `Local Storage/leveldb/` - Primary token storage
+
+### What Gets Extracted
+
+- **token**: User token (starts with a base64-encoded user ID)
+- **guilds**: All servers you're a member of
+
+## Multi-Guild Management
+
+### List Guilds
+
+See all available guilds:
+
+```bash
+agent-discord guild list
+```
+
+Output:
+```json
+[
+  {
+    "id": "1234567890123456789",
+    "name": "My Server",
+    "current": true
+  },
+  {
+    "id": "9876543210987654321",
+    "name": "Another Server",
+    "current": false
+  }
+]
+```
+
+### Switch Guild
+
+Change the active guild:
+
+```bash
+agent-discord guild switch 9876543210987654321
+```
+
+All subsequent commands will use the selected guild until you switch again.
+
+### Current Guild
+
+Check which guild is active:
+
+```bash
+agent-discord guild current
+```
+
+## Credential Storage
+
+### Location
+
+Credentials are stored in:
+```
+~/.config/agent-messenger/discord-credentials.json
+```
+
+### Format
+
+```json
+{
+  "token": "user_token_here",
+  "current_guild": "1234567890123456789",
+  "guilds": {
+    "1234567890123456789": {
+      "guild_id": "1234567890123456789",
+      "guild_name": "My Server"
+    },
+    "9876543210987654321": {
+      "guild_id": "9876543210987654321",
+      "guild_name": "Another Server"
+    }
+  }
+}
+```
+
+### Security
+
+- File permissions: `0600` (owner read/write only)
+- Tokens are stored in plaintext (same as Discord desktop app)
+- Keep this file secure - it grants full access to your Discord account
+
+## Authentication Status
+
+Check if you're authenticated:
+
+```bash
+agent-discord auth status
+```
+
+Output when authenticated:
+```json
+{
+  "authenticated": true,
+  "user": "username",
+  "current_guild": "1234567890123456789",
+  "guilds_count": 5
+}
+```
+
+Output when not authenticated:
+```json
+{
+  "error": "Not authenticated. Run \"auth extract\" first."
+}
+```
+
+## Token Lifecycle
+
+### When Tokens Expire
+
+Discord user tokens can be invalidated when:
+- You change your password
+- You enable/disable 2FA
+- Discord forces a logout
+- You manually log out of the desktop app
+
+### Re-authentication
+
+If commands start failing with auth errors:
+
+```bash
+# Re-extract credentials
+agent-discord auth extract
+
+# Verify it worked
+agent-discord auth status
+```
+
+## Troubleshooting
+
+### Using Debug Mode
+
+For any extraction issues, run with `--debug` to see detailed information:
+
+```bash
+agent-discord auth extract --debug
+```
+
+This shows:
+- Which Discord directory was found
+- Token extraction progress
+- Token validation results
+- Guild discovery details
+
+### "Discord desktop app not found"
+
+**Cause**: Discord desktop app not installed or in non-standard location
+
+**Solution**:
+1. Install Discord desktop app
+2. Log in to your account
+3. Run `agent-discord auth extract` again
+
+### "No Discord token found"
+
+**Cause**: Not logged into Discord or token storage corrupted
+
+**Solution**:
+1. Open Discord desktop app
+2. Make sure you're logged in (can see your servers)
+3. Run `agent-discord auth extract --debug` to see details
+
+### "Permission denied reading Discord data"
+
+**Cause**: Insufficient file system permissions
+
+**Solution** (macOS):
+1. Grant Terminal/iTerm full disk access in System Preferences
+2. Security & Privacy -> Privacy -> Full Disk Access
+3. Add your terminal application
+
+### "Token validation failed" errors
+
+**Cause**: Token expired or invalidated
+
+**Solution**:
+```bash
+# Re-extract fresh credentials
+agent-discord auth extract
+
+# Test authentication
+agent-discord auth status
+```
+
+## Security Considerations
+
+### What agent-discord Can Access
+
+With extracted credentials, agent-discord has the same permissions as you in Discord:
+- Read all channels you have access to
+- Send messages as you
+- Upload/download files
+- Manage reactions
+- Access user information
+- View server member lists
+
+### What agent-discord Cannot Do
+
+- Access channels you don't have permission for
+- Perform admin operations (unless you're an admin)
+- Access other users' DMs without existing conversation
+- Manage server settings (not implemented)
+
+### Best Practices
+
+1. **Protect credentials.json**: Never commit to version control
+2. **Use guild switching**: Keep different contexts separate
+3. **Re-extract periodically**: Keep tokens fresh
+4. **Revoke if compromised**: Change your Discord password to invalidate tokens
+
+## Manual Token Management (Advanced)
+
+If automatic extraction fails, you can manually create credentials:
+
+```bash
+# Create config directory
+mkdir -p ~/.config/agent-messenger
+
+# Create credentials file
+cat > ~/.config/agent-messenger/discord-credentials.json << 'EOF'
+{
+  "token": "YOUR_TOKEN_HERE",
+  "current_guild": "1234567890123456789",
+  "guilds": {
+    "1234567890123456789": {
+      "guild_id": "1234567890123456789",
+      "guild_name": "My Server"
+    }
+  }
+}
+EOF
+
+# Set secure permissions
+chmod 600 ~/.config/agent-messenger/discord-credentials.json
+```
+
+To find your token manually:
+1. Open Discord in browser (not desktop app)
+2. Open DevTools -> Network tab
+3. Make any API call (send message, etc.)
+4. Find request to `discord.com/api`
+5. Copy `Authorization` header value
+
+**Warning**: Self-botting (using user tokens for automation) may violate Discord's Terms of Service. Use responsibly and at your own risk.