agent-messenger 1.0.0 → 1.2.0

package/docs/content/docs/agent-skills.mdx

@@ -0,0 +1,98 @@
+---
+title: Agent Skills
+description: Teach your AI agent how to use Agent Messenger CLIs effectively.
+icon: Hexagon
+---
+
+Agent Skills are instruction files that teach AI coding agents how to use tools effectively. Agent Messenger includes skills for Slack, Discord, and Teams.
+
+## What Are Agent Skills?
+
+When you give an AI agent access to a CLI tool, it needs to know:
+- What commands are available
+- How to format arguments
+- What output to expect
+- Best practices and common patterns
+
+Agent Skills provide this knowledge in a structured format that AI agents can understand.
+
+## Installation
+
+### Skills CLI
+
+The fastest way to add Agent Messenger skills to your project:
+
+```bash
+npx skills add devxoul/agent-messenger
+```
+
+This adds the skill files to your project's `.skills/` directory.
+
+### Claude Code
+
+Add Agent Messenger skills to Claude Code:
+
+```bash
+# From terminal
+claude plugin marketplace add devxoul/agent-messenger
+claude plugin install agent-messenger
+```
+
+Or from within Claude Code:
+
+```
+/plugin marketplace add devxoul/agent-messenger
+/plugin install agent-messenger
+```
+
+### OpenCode
+
+Add to your `opencode.jsonc`:
+
+```jsonc
+{
+  "plugins": [
+    "agent-messenger@1.1.0"
+  ]
+}
+```
+
+## How It Works
+
+Once installed, your AI agent can:
+
+1. **Understand the CLI** - Know what commands exist and how to use them
+2. **Extract credentials** - Run `agent-slack auth extract` automatically
+3. **Send messages** - Compose and send messages on your behalf
+4. **Read context** - Get workspace snapshots to understand conversations
+5. **React appropriately** - Add reactions, reply in threads, etc.
+
+## Example Interaction
+
+With Agent Messenger skills installed, you can ask your AI agent:
+
+> "Send a message to #general saying the build passed"
+
+The agent will:
+1. Check if credentials are configured
+2. Run `agent-slack auth extract` if needed
+3. Execute `agent-slack message send general "The build passed"`
+4. Confirm the message was sent
+
+## Skill Contents
+
+Each platform skill includes:
+
+| Section | Description |
+|---------|-------------|
+| **Authentication** | How to extract and manage tokens |
+| **Commands** | Full command reference with examples |
+| **Output Format** | Expected JSON structure for parsing |
+| **Error Handling** | Common errors and how to recover |
+| **Best Practices** | Tips for reliable agent workflows |
+
+## Learn More
+
+- [Agent Skills Documentation](https://agentskills.io/)
+- [Skills CLI](https://skills.sh/)
+- [GitHub Repository](https://github.com/devxoul/agent-messenger)

package/docs/content/docs/index.mdx

@@ -0,0 +1,124 @@
+---
+title: What is Agent Messenger?
+description: Give your AI agent the power to read and send messages across Slack, Discord, Teams and more
+icon: Info
+---
+
+Agent Messenger is a unified, agent-friendly CLI for messaging platforms. It automatically extracts credentials from your desktop apps—no OAuth flows, no API keys, no admin approval needed.
+
+## Why Agent Messenger?
+
+### For AI Agents
+
+AI agents need to communicate with humans through messaging platforms. But integrating with Slack, Discord, or Teams traditionally requires:
+
+- **OAuth setup** - Creating apps, getting admin approval, managing tokens
+- **API keys** - Storing secrets, handling rotation, security concerns
+- **Platform-specific code** - Learning different APIs for each platform
+
+Agent Messenger eliminates all of this. Your agent can start sending messages in seconds.
+
+### For Developers
+
+Building AI-powered workflows that interact with messaging platforms shouldn't require a week of OAuth debugging. Agent Messenger provides:
+
+- **Zero configuration** - Extract tokens from your existing desktop apps
+- **Unified interface** - Same commands work across all platforms
+- **JSON output** - Perfect for piping into other tools or LLMs
+
+## How It Works
+
+Agent Messenger reads authentication tokens directly from your installed desktop apps (Slack, Discord, Teams). These apps store session tokens locally, and Agent Messenger safely extracts them.
+
+```bash
+# Extract credentials from Slack desktop app
+agent-slack auth extract
+
+# That's it! Now you can send messages
+agent-slack message send general "Hello from my AI agent!"
+```
+
+No app creation. No admin approval. No waiting.
+
+## Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **Auto-extraction** | Pulls tokens from desktop apps automatically |
+| **Multi-platform** | Slack, Discord, and Microsoft Teams |
+| **Multi-workspace** | Switch between workspaces/servers easily |
+| **JSON output** | Machine-readable by default, `--pretty` for humans |
+| **Comprehensive** | Messages, channels, users, reactions, files |
+
+## Why Not MCP?
+
+The Model Context Protocol (MCP) is a popular way to give AI agents access to external tools. But it has a fundamental problem: **context bloat**.
+
+MCP servers expose all their tools at once. When you connect an MCP server with 50 tools, your AI agent's context window fills up with 50 tool descriptions—even if it only needs one.
+
+**Agent Skills + CLI is better:**
+
+| MCP Approach | Agent Skills Approach |
+|--------------|----------------------|
+| All tools loaded at once | Load only what you need |
+| Bloated context window | Minimal token usage |
+| Agent confused by options | Focused, relevant tools |
+| Static tool definitions | Dynamic skill loading |
+
+With Agent Messenger, your AI agent loads the skill it needs, uses the CLI, and moves on. No wasted tokens.
+
+## Why Not OAuth?
+
+Traditional Slack/Discord/Teams integrations require OAuth:
+
+1. Create an app in the platform's developer portal
+2. Configure OAuth scopes and redirect URLs
+3. Submit for workspace admin approval
+4. Wait days (or weeks) for approval
+5. Handle token refresh, storage, and rotation
+
+**Agent Messenger skips all of this.**
+
+Your desktop apps already have valid session tokens. Agent Messenger extracts them directly, so you can start sending messages immediately.
+
+### When OAuth Makes Sense
+
+OAuth is better when you need:
+- **Server-side bots** - Running 24/7 without your desktop app
+- **Multi-user applications** - Many users authenticating separately
+- **Granular permissions** - Fine-tuned access control
+
+Bot support is on our roadmap for these use cases.
+
+## Design Principles
+
+### Zero Configuration
+
+The best setup is no setup. Agent Messenger should work the moment you install it.
+
+### AI-First, Human-Friendly
+
+Default output is JSON for machines. Add `--pretty` for humans. Both are first-class citizens.
+
+### Unified Interface
+
+Learn once, use everywhere. The same commands work across Slack, Discord, and Teams.
+
+### Fail Fast, Fail Clear
+
+When something goes wrong, tell the user exactly what and how to fix it. No cryptic error codes.
+
+### Respect Privacy
+
+Tokens stay on your machine. Nothing is sent to external servers. Your credentials are yours.
+
+## Next Steps
+
+- [Quick Start](/docs/quick-start) - Get running in 30 seconds
+- [Slack](/docs/integrations/slack) - Full Slack command reference
+- [Discord](/docs/integrations/discord) - Full Discord command reference
+- [Teams](/docs/integrations/teams) - Full Teams command reference
+
+## Inspiration
+
+Agent Messenger is inspired by [agent-browser](https://github.com/vercel-labs/agent-browser) from Vercel Labs, which takes a similar approach to browser automation for AI agents.

package/docs/{discord.md → content/docs/integrations/discord.mdx}

@@ -1,8 +1,9 @@
-# Discord Integration
+---
+title: Discord
+description: Complete reference for the agent-discord CLI.
+---
 
-Detailed documentation for Discord integration in agent-messenger.
-
-> **Note**: `agent-discord` is a convenient shortcut for `agent-messenger discord`.
+> **Tip**: `agent-discord` is a shortcut for `agent-messenger discord`.
 
 ## Quick Start
 
@@ -10,7 +11,7 @@ Detailed documentation for Discord integration in agent-messenger.
 # 1. Extract credentials from Discord desktop app (zero-config!)
 agent-discord auth extract
 
-# 2. Get guild snapshot
+# 2. Get server snapshot
 agent-discord snapshot
 
 # 3. Send a message
@@ -34,7 +35,7 @@ This command:
 - Auto-detects your platform (macOS/Linux/Windows)
 - Extracts Discord user token from the desktop app
 - Validates token against Discord API
-- Discovers ALL joined guilds (servers)
+- Discovers ALL joined servers
 - Stores credentials securely in `~/.config/agent-messenger/`
 
 ### Authentication Commands
@@ -47,22 +48,22 @@ agent-discord auth status
 agent-discord auth logout
 ```
 
-## Guild Management
+## Server Management
 
-Discord uses "guilds" (servers) instead of workspaces. You must select a guild before using most commands.
+You must select a server before using most commands.
 
 ```bash
-# List all guilds
-agent-discord guild list
+# List all servers
+agent-discord server list
 
-# Switch to a different guild
-agent-discord guild switch <guild-id>
+# Switch to a different server
+agent-discord server switch <server-id>
 
-# Show current guild
-agent-discord guild current
+# Show current server
+agent-discord server current
 
-# Get guild info
-agent-discord guild info <guild-id>
+# Get server info
+agent-discord server info <server-id>
 ```
 
 ## Commands
@@ -83,12 +84,36 @@ agent-discord message get <channel-id> <message-id>
 
 # Delete a message
 agent-discord message delete <channel-id> <message-id> --force
+
+# Search messages in current server
+agent-discord message search <query>
+agent-discord message search "bug fix"
+
+# Search with filters
+agent-discord message search "meeting" --channel 123456789
+agent-discord message search "report" --author 987654321
+agent-discord message search "screenshot" --has image
+
+# Search with sorting and pagination
+agent-discord message search "hello" --sort timestamp --sort-dir desc
+agent-discord message search "test" --limit 10 --offset 20
 ```
 
+**Search Options:**
+- `--channel <id>` - Filter by specific channel
+- `--author <id>` - Filter by specific author
+- `--has <type>` - Filter by attachment type: `file`, `image`, `video`, `embed`, `link`, `sticker`
+- `--sort <type>` - Sort by: `timestamp` (default), `relevance`
+- `--sort-dir <dir>` - Sort direction: `asc`, `desc` (default)
+- `--limit <n>` - Number of results (max 25, default 25)
+- `--offset <n>` - Pagination offset (default 0)
+
+> **Note:** Search requires a current server to be set. Use `agent-discord server switch <server-id>` first.
+
 ### Channel Commands
 
 ```bash
-# List channels in current guild
+# List channels in current server
 agent-discord channel list
 
 # Get channel info
@@ -102,7 +127,7 @@ agent-discord channel history 123456789 --limit 100
 ### User Commands
 
 ```bash
-# List guild members
+# List server members
 agent-discord user list
 
 # Get user info
@@ -142,7 +167,7 @@ agent-discord file info <channel-id> <file-id>
 
 ### Snapshot Command
 
-Get comprehensive guild state for AI agents:
+Get comprehensive server state for AI agents:
 
 ```bash
 # Full snapshot (channels, members, recent messages)
@@ -162,14 +187,14 @@ All commands support these options:
 
 ```bash
 --pretty    # Pretty-print JSON output (default is compact JSON)
---guild <id>  # Use specific guild (overrides current guild)
+--server <id>  # Use specific server (overrides current server)
 ```
 
 ## Key Differences from Slack
 
 | Concept | Slack | Discord |
 |---------|-------|---------|
-| Server | Workspace | Guild |
+| Server | Workspace | Server |
 | Channel ID | Alphanumeric (C01234567) | Numeric snowflake (123456789012345678) |
 | Message ID | Timestamp (1234567890.123456) | Numeric snowflake (123456789012345678) |
 | User ID | Alphanumeric (U01234567) | Numeric snowflake (123456789012345678) |

package/docs/content/docs/integrations/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Integrations",
+  "icon": "Plug",
+  "pages": ["slack", "discord", "teams"]
+}

package/docs/{slack.md → content/docs/integrations/slack.mdx}

@@ -1,8 +1,9 @@
-# Slack Integration
+---
+title: Slack
+description: Complete reference for the agent-slack CLI.
+---
 
-Detailed documentation for Slack integration in agent-messenger.
-
-> **Note**: `agent-slack` is a convenient shortcut for `agent-messenger slack`.
+> **Tip**: `agent-slack` is a shortcut for `agent-messenger slack`.
 
 ## Quick Start
 

package/docs/content/docs/integrations/teams.mdx

@@ -0,0 +1,322 @@
+---
+title: Teams
+description: Complete reference for the agent-teams CLI.
+---
+
+> **Tip**: `agent-teams` is a shortcut for `agent-messenger teams`.
+
+## Quick Start
+
+```bash
+# 1. Extract credentials from Teams desktop app (zero-config!)
+agent-teams auth extract
+
+# 2. Get team snapshot
+agent-teams snapshot
+
+# 3. Send a message
+agent-teams message send <channel-id> "Hello from AI agent!"
+```
+
+## Authentication
+
+### Seamless Token Extraction
+
+agent-teams automatically extracts your Microsoft Teams credentials from the desktop app:
+
+```bash
+agent-teams auth extract
+
+# Use --debug for troubleshooting
+agent-teams auth extract --debug
+```
+
+This command:
+- Auto-detects your platform (macOS/Linux/Windows)
+- Extracts Teams access token from the desktop app
+- Validates token against Teams API
+- Discovers ALL joined teams
+- Stores credentials securely in `~/.config/agent-messenger/`
+
+### ⚠️ TOKEN EXPIRY WARNING
+
+**Teams tokens expire in 60-90 minutes!** Unlike Slack and Discord tokens which last much longer, Microsoft Teams uses short-lived OAuth tokens.
+
+```bash
+# Check if your token is still valid
+agent-teams auth status
+
+# Re-extract when expired (just run extract again)
+agent-teams auth extract
+```
+
+**Best practices for AI agents:**
+- Always check `auth status` before operations
+- Re-run `auth extract` if you get 401 errors
+- Consider automating token refresh in long-running workflows
+
+### Authentication Commands
+
+```bash
+# Check auth status (shows expiry time!)
+agent-teams auth status
+
+# Logout (clear stored credentials)
+agent-teams auth logout
+```
+
+### Supported Teams Versions
+
+agent-teams supports both **New Teams** (WebView2-based, com.microsoft.teams2) and **Classic Teams**:
+
+| Version | macOS | Windows | Linux |
+|---------|:-----:|:-------:|:-----:|
+| New Teams | ✅ | ✅ | N/A |
+| Classic Teams | ✅ | ✅ | ✅ |
+
+### Manual Token Input (Last Resort)
+
+If automatic extraction fails, you can manually provide a token:
+
+```bash
+agent-teams auth extract --token <your-skype-token>
+```
+
+**How to get your token manually:**
+
+1. Open Microsoft Teams in your browser (teams.microsoft.com)
+2. Open Developer Tools (F12 or Cmd+Option+I)
+3. Go to **Application** > **Cookies** > `https://teams.microsoft.com`
+4. Find the cookie named `skypetoken_asm`
+5. Copy the **Value** (it's a long string starting with `eyJ...`)
+6. Run: `agent-teams auth extract --token "eyJ..."`
+
+> **Note**: Browser tokens also expire in 60-90 minutes. For long-running workflows, you may need to refresh periodically.
+
+## Team Management
+
+Teams uses "teams" as the top-level organizational unit. You must select a team before using most commands.
+
+```bash
+# List all teams
+agent-teams team list
+
+# Switch to a different team
+agent-teams team switch <team-id>
+
+# Show current team
+agent-teams team current
+
+# Get team info
+agent-teams team info <team-id>
+```
+
+## Commands
+
+### Message Commands
+
+```bash
+# Send a message
+agent-teams message send <channel-id> <content>
+agent-teams message send abc123-def456 "Hello world"
+
+# List messages
+agent-teams message list <channel-id>
+agent-teams message list abc123-def456 --limit 50
+
+# Get a specific message
+agent-teams message get <channel-id> <message-id>
+
+# Delete a message
+agent-teams message delete <channel-id> <message-id> --force
+
+# Reply to a message (thread)
+agent-teams message reply <channel-id> <message-id> "Reply content"
+```
+
+### Channel Commands
+
+```bash
+# List channels in current team
+agent-teams channel list
+
+# Get channel info
+agent-teams channel info <channel-id>
+
+# Get channel message history
+agent-teams channel history <channel-id>
+agent-teams channel history abc123-def456 --limit 100
+```
+
+### User Commands
+
+```bash
+# List team members
+agent-teams user list
+
+# Get user info
+agent-teams user info <user-id>
+
+# Get current authenticated user
+agent-teams user me
+```
+
+### Reaction Commands
+
+```bash
+# Add reaction
+agent-teams reaction add <channel-id> <message-id> <emoji>
+agent-teams reaction add abc123-def456 msg789 like
+
+# Remove reaction
+agent-teams reaction remove <channel-id> <message-id> <emoji>
+
+# List reactions on a message
+agent-teams reaction list <channel-id> <message-id>
+```
+
+### File Commands
+
+```bash
+# Upload file to channel
+agent-teams file upload <channel-id> <path>
+agent-teams file upload abc123-def456 ./report.pdf
+
+# List files in channel
+agent-teams file list <channel-id>
+
+# Get file info
+agent-teams file info <channel-id> <file-id>
+
+# Download file
+agent-teams file download <file-id> <output-path>
+```
+
+### Snapshot Command
+
+Get comprehensive team state for AI agents:
+
+```bash
+# Full snapshot (channels, members, recent messages)
+agent-teams snapshot
+
+# Filtered snapshots
+agent-teams snapshot --channels-only
+agent-teams snapshot --users-only
+
+# Limit messages per channel
+agent-teams snapshot --limit 10
+```
+
+## Global Options
+
+All commands support these options:
+
+```bash
+--pretty      # Pretty-print JSON output (default is compact JSON)
+--team <id>   # Use specific team (overrides current team)
+```
+
+## Key Differences: Teams vs Discord vs Slack
+
+| Concept | Slack | Discord | Teams |
+|---------|-------|---------|-------|
+| Server/Workspace | Workspace | Guild | Team |
+| Channel ID format | Alphanumeric (C01234567) | Numeric snowflake | UUID (abc123-def456-...) |
+| Message ID format | Timestamp (1234567890.123456) | Numeric snowflake | UUID |
+| User ID format | Alphanumeric (U01234567) | Numeric snowflake | UUID (Azure AD Object ID) |
+| Token lifetime | Long-lived | Long-lived | **60-90 minutes** |
+| API | Slack Web API | Discord API | Teams Messaging API |
+| Threads | Thread timestamps | Thread channels | Reply chains |
+| Rate limits | Moderate | Moderate | Strict |
+
+## Troubleshooting
+
+### Token Expired (401 Unauthorized)
+
+```bash
+# Teams tokens expire in 60-90 minutes! To refresh:
+# 1. Open Microsoft Teams desktop app
+# 2. Send any message (this refreshes your session cookies)
+# 3. Re-extract:
+agent-teams auth extract
+```
+
+### "No teams found"
+
+Ensure you're a member of at least one team in the Teams desktop app, then:
+```bash
+agent-teams auth extract --debug
+```
+
+### "Channel not found"
+
+Teams channel IDs are UUIDs. Make sure you're using the full ID:
+```bash
+# Get channel list to find correct IDs
+agent-teams channel list --pretty
+```
+
+### Rate Limiting (429 Too Many Requests)
+
+Teams API has strict rate limits. Wait and retry:
+```bash
+# Add delays between operations in scripts
+sleep 2
+```
+
+### Desktop App Not Detected
+
+Ensure Teams desktop app is:
+1. Installed (not just web version)
+2. Currently running
+3. Signed in to your account
+
+```bash
+# Debug extraction
+agent-teams auth extract --debug
+```
+
+### Permission Errors
+
+Some operations require specific Microsoft 365 permissions. Check with your IT admin if you encounter persistent 403 errors.
+
+## AI Agent Integration
+
+See `skills/agent-messenger/` directory for:
+- Complete skill documentation
+- Runnable templates
+
+### Example: AI Agent Workflow
+
+```bash
+#!/bin/bash
+# Example: Daily standup automation
+
+# 1. Check auth (re-extract if needed)
+if ! agent-teams auth status | grep -q "valid"; then
+  agent-teams auth extract
+fi
+
+# 2. Get team context
+agent-teams snapshot --limit 5 > /tmp/teams-context.json
+
+# 3. Send standup reminder
+agent-teams message send $STANDUP_CHANNEL "🌅 Good morning! Time for standup."
+```
+
+### Token Refresh Pattern for Long-Running Agents
+
+```bash
+# Wrapper function for token-aware operations
+teams_cmd() {
+  # Check token validity
+  if ! agent-teams auth status 2>/dev/null | grep -q "valid"; then
+    agent-teams auth extract
+  fi
+  agent-teams "$@"
+}
+
+# Usage
+teams_cmd message send $CHANNEL "Hello!"
+```

package/docs/content/docs/meta.json

@@ -0,0 +1,8 @@
+{
+  "pages": [
+    "index",
+    "quick-start",
+    "integrations",
+    "agent-skills"
+  ]
+}