agent-messenger 1.15.0 → 2.0.0

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

@@ -4,7 +4,7 @@ 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, Teams, and Channel Talk (beta).
+Agent Skills are instruction files that teach AI coding agents how to use tools effectively. Agent Messenger includes skills for Slack, Discord, Teams, Telegram, WhatsApp, LINE, Instagram, KakaoTalk, and Channel Talk (beta).
 
 ## What Are Agent Skills?
 

package/docs/content/docs/{integrations → cli}/channeltalk.mdx

@@ -1,9 +1,9 @@
 ---
-title: Channel Talk (Beta)
+title: Channel Talk
 description: Complete reference for the agent-channeltalk CLI.
 ---
 
-> **Beta**: Channel Talk support is in beta. Some features may change. macOS only.
+> **Beta**: Channel Talk support is in beta. Some features may change. macOS and Windows only.
 
 > **Tip**: `agent-channeltalk` is a shortcut for `agent-messenger channeltalk`.
 
@@ -207,7 +207,7 @@ All commands support these options:
 | Multi-workspace            |            ✅            |             ✅             |
 | CI/CD friendly             |            —             |             ✅             |
 
-Use **agent-channeltalk** when you want zero-config access acting as yourself. Use **[agent-channeltalkbot](/docs/integrations/channeltalkbot)** for server-side automation, CI/CD pipelines, or when you need bot-specific features like closing chats.
+Use **agent-channeltalk** when you want zero-config access acting as yourself. Use **[agent-channeltalkbot](/docs/cli/channeltalkbot)** for server-side automation, CI/CD pipelines, or when you need bot-specific features like closing chats.
 
 ## Troubleshooting
 
@@ -215,10 +215,14 @@ Use **agent-channeltalk** when you want zero-config access acting as yourself. U
 
 The CLI looks for the Channel Talk desktop app's cookie database in:
 
+**macOS:**
 1. `~/Library/Containers/com.zoyi.channel.desk.osx/Data/Library/Application Support/Channel Talk/Cookies` (Mac App Store)
 2. `~/Library/Application Support/Channel Talk/Cookies` (Electron version)
 
-If neither exists, install the Channel Talk desktop app and log in.
+**Windows:**
+1. `%APPDATA%\Channel Talk\Network\Cookies`
+
+If none exist, install the Channel Talk desktop app and log in.
 
 ### Cookies expired
 
@@ -242,7 +246,7 @@ npx -y agent-messenger channeltalk snapshot --pretty
 
 ## Limitations
 
-- macOS only (Channel Talk desktop app required)
+- macOS and Windows only (Channel Talk desktop app required)
 - No real-time events / WebSocket connection
 - No file upload support
 - No message editing or deletion

package/docs/content/docs/{integrations → cli}/channeltalkbot.mdx

@@ -1,5 +1,5 @@
 ---
-title: Channel Talk Bot (Beta)
+title: Channel Talk Bot
 description: Complete reference for the agent-channeltalkbot CLI.
 ---
 

package/docs/content/docs/cli/instagram.mdx

@@ -0,0 +1,211 @@
+---
+title: Instagram
+description: Complete reference for the agent-instagram CLI.
+---
+
+> **Tip**: After `npm install -g agent-messenger`, `agent-instagram` is available directly. For one-off execution without a global install you can use `npm exec --package agent-messenger agent-instagram ...`, `pnpm dlx --package agent-messenger agent-instagram ...`, `yarn dlx agent-messenger agent-instagram ...`, or `bunx --package agent-messenger agent-instagram ...`.
+
+## Requirements
+
+Instagram integration uses a private mobile API (not the official Graph API). No new npm dependencies are required:
+
+- Authenticates with **username and password**, with support for 2FA and login challenges.
+- Each command makes HTTP requests on demand. No persistent connection or background process.
+- Multiple Instagram accounts can be linked simultaneously.
+
+## Quick Start
+
+```bash
+# Log in with your Instagram credentials
+agent-instagram auth login
+
+# List DM threads
+agent-instagram chat list
+
+# Send a message
+agent-instagram message send 12345678901 "Hello from agent-instagram"
+```
+
+## Authentication
+
+### Username/Password Login
+
+The CLI authenticates as a mobile client using your Instagram username and password. Your existing app sessions are never affected.
+
+**Interactive mode** (TTY): prompts for credentials automatically.
+
+```bash
+agent-instagram auth login
+```
+
+**Non-interactive mode** (CI / agents): pass credentials as flags.
+
+```bash
+agent-instagram auth login --username your_username --password your_password
+```
+
+### Two-Factor Authentication
+
+If 2FA is enabled, the CLI handles it automatically in interactive mode. In non-interactive mode, use a separate verify step:
+
+```bash
+agent-instagram auth verify --username your_username --code 123456 --identifier <two_factor_identifier>
+```
+
+The `--identifier` value comes from the login response's `two_factor_identifier` field.
+
+### Challenge Required
+
+Instagram may require a challenge for logins from new devices or locations. The CLI resolves challenges interactively when possible. In non-interactive mode:
+
+```bash
+agent-instagram auth challenge --username your_username --method email
+agent-instagram auth challenge --username your_username --code 123456
+```
+
+### Debug Mode
+
+Use `--debug` on login to see raw API responses when troubleshooting:
+
+```bash
+agent-instagram auth login --username your_username --password your_password --debug
+```
+
+### Account Management
+
+```bash
+# Check current auth state
+agent-instagram auth status
+agent-instagram auth status --account <id>
+
+# List linked accounts
+agent-instagram auth list
+
+# Switch active account
+agent-instagram auth use <id>
+
+# Remove stored session
+agent-instagram auth logout
+agent-instagram auth logout --account <id>
+```
+
+## Commands
+
+### Chat Commands
+
+```bash
+# List DM threads (sorted by most recent activity)
+agent-instagram chat list
+agent-instagram chat list --limit 50
+agent-instagram chat list --account <id>
+
+# Search threads by name
+agent-instagram chat search "project"
+agent-instagram chat search "project" --limit 10
+agent-instagram chat search "project" --account <id>
+```
+
+### Message Commands
+
+```bash
+# List messages in a thread
+agent-instagram message list <thread> --limit 20
+agent-instagram message list 12345678901 --limit 50
+
+# Send a text message by thread ID
+agent-instagram message send <thread> <text>
+agent-instagram message send 12345678901 "Hello!"
+
+# Send a text message by username (resolves the user first)
+agent-instagram message send-to <username> <text>
+agent-instagram message send-to alice "Hello!"
+
+# Search messages by text content
+agent-instagram message search <query>
+agent-instagram message search "meeting notes" --thread 12345678901
+agent-instagram message search "hello" --limit 10
+
+# Search for users by name or username
+agent-instagram message search-users <query>
+agent-instagram message search-users "alice"
+```
+
+Thread IDs are numeric strings returned by `chat list` (e.g. `340282366841710300949128138443434234567`).
+
+## Global Options
+
+| Option           | Description                                |
+| ---------------- | ------------------------------------------ |
+| `--pretty`       | Human-readable output instead of JSON      |
+| `--account <id>` | Use a specific account for this command     |
+
+## Storage
+
+- Credentials stored in `~/.config/agent-messenger/instagram-credentials.json`
+- Session data stored in `~/.config/agent-messenger/instagram/<account-id>/`
+
+## Limitations
+
+- **HTTP on demand**: Each command makes HTTP requests and returns. No persistent daemon or WebSocket connection.
+- **Ban risk**: Instagram monitors for automated behavior. Avoid high-volume messaging, rapid-fire sends, or bulk operations. Space out commands when sending multiple messages.
+- **No file uploads or downloads**
+- **No voice or video calls**
+- **No Stories, Reels, or Feed access**
+- **Private API**: This uses Instagram's private mobile API, not the official Graph API. Behavior may change without notice.
+
+## Troubleshooting
+
+### `agent-instagram: command not found`
+
+**`agent-instagram` is NOT the npm package name.** The npm package is `agent-messenger`.
+
+```bash
+# If installed globally
+agent-instagram chat list --pretty
+
+# If not installed, use --package
+npx -y --package agent-messenger agent-instagram chat list --pretty
+```
+
+**NEVER run `npx agent-instagram`** without `--package agent-messenger`. It will fail or install a wrong package.
+
+### Login fails with "challenge_required"
+
+Instagram flagged the login as suspicious. Complete the challenge:
+
+```bash
+# Check what challenge is pending
+agent-instagram auth challenge --status
+
+# Submit the code sent to your email or phone
+agent-instagram auth challenge --code 123456
+```
+
+If challenges keep appearing, try logging in from the Instagram app first to "warm up" the account, then retry the CLI.
+
+### Login fails with "two_factor_required"
+
+Your account has 2FA enabled. Complete the verification:
+
+```bash
+agent-instagram auth verify --code 123456
+```
+
+### Session expired
+
+Instagram may invalidate sessions after extended inactivity or password changes. If commands start failing:
+
+```bash
+# Check if still authenticated
+agent-instagram auth status
+
+# Re-login if needed
+agent-instagram auth login
+```
+
+## AI Agent Integration
+
+See [`skills/agent-instagram/`](https://github.com/devxoul/agent-messenger/tree/main/skills/agent-instagram) for:
+
+- Complete skill documentation
+- Common patterns for AI agent workflows

package/docs/content/docs/cli/kakaotalk.mdx

@@ -0,0 +1,286 @@
+---
+title: KakaoTalk
+description: Complete reference for the agent-kakaotalk CLI.
+---
+
+> **Tip**: After `npm install -g agent-messenger`, `agent-kakaotalk` is available directly. For one-off execution without a global install you can use `npm exec --package agent-messenger agent-kakaotalk ...`, `pnpm dlx --package agent-messenger agent-kakaotalk ...`, `yarn dlx agent-messenger agent-kakaotalk ...`, or `bunx --package agent-messenger agent-kakaotalk ...`.
+
+## Key Concepts
+
+Before diving in, a few things about KakaoTalk's architecture:
+
+| Term                       | Description                                                                                         |
+| -------------------------- | --------------------------------------------------------------------------------------------------- |
+| **LOCO protocol**          | KakaoTalk's binary messaging protocol. The CLI handles this internally — you never touch it.        |
+| **Chat room**              | A conversation (1:1, group, or open chat). Referenced by a numeric chat ID.                         |
+| **Device slots**           | KakaoTalk allows one phone + one PC + one tablet session simultaneously.                            |
+| **Sub-device**             | A secondary device (PC or tablet). The CLI logs in as a sub-device so your phone session is never affected. |
+| **Passcode verification**  | When registering a new device, KakaoTalk displays a code that you confirm on your phone.            |
+| **Log ID**                 | A unique numeric identifier for each message, used for pagination.                                  |
+
+## Quick Start
+
+```bash
+# 1. Login (registers as sub-device — desktop app stays running)
+agent-kakaotalk auth login
+
+# 2. List chat rooms
+agent-kakaotalk chat list
+
+# 3. Send a message
+agent-kakaotalk message send <chat-id> "Hello from agent-kakaotalk!"
+
+# 4. List messages in a chat
+agent-kakaotalk message list <chat-id>
+```
+
+## Authentication
+
+KakaoTalk offers two authentication methods. **Login** is recommended because it registers the CLI as a sub-device and keeps your desktop app running.
+
+### Method 1: Login (Recommended)
+
+Registers the CLI as a sub-device using the **tablet** slot by default. Your desktop app keeps running.
+
+```bash
+# Interactive — prompts for email and password
+agent-kakaotalk auth login
+
+# Non-interactive (for AI agents)
+agent-kakaotalk auth login --email user@example.com --password mypass
+```
+
+On first login, KakaoTalk requires device verification:
+
+1. The CLI requests a passcode from KakaoTalk's server
+2. A numeric code is displayed in the terminal
+3. Enter the code on your phone when prompted
+4. The CLI polls until you confirm — login completes automatically
+
+### Method 2: Extract from Desktop App
+
+Extracts OAuth tokens directly from the KakaoTalk desktop app's cache. This **kicks the desktop session** because it reuses the desktop's credentials.
+
+```bash
+agent-kakaotalk auth extract
+agent-kakaotalk auth extract --debug
+```
+
+### Device Slots
+
+KakaoTalk allows these simultaneous sessions:
+
+- **Phone** — always active, never affected by the CLI
+- **PC** — will kick KakaoTalk desktop if the CLI uses this slot
+- **Tablet** (default) — safe if you don't use a tablet for KakaoTalk
+
+```bash
+# Default: tablet slot (safe for most users)
+agent-kakaotalk auth login
+
+# Use PC slot instead (kicks desktop app)
+agent-kakaotalk auth login --device-type pc
+
+# Force login even if slot is occupied
+agent-kakaotalk auth login --device-type tablet --force
+```
+
+### Auth Management
+
+```bash
+# Check auth status
+agent-kakaotalk auth status
+agent-kakaotalk auth status --account <account-id>
+
+# List all stored accounts
+agent-kakaotalk auth list
+
+# Switch the current account
+agent-kakaotalk auth use <account-id>
+
+# Remove stored credentials
+agent-kakaotalk auth logout
+agent-kakaotalk auth logout --account <account-id>
+```
+
+## Multi-Account
+
+KakaoTalk supports multiple accounts. Each login or extraction stores credentials separately, keyed by user ID.
+
+```bash
+# List all stored accounts
+agent-kakaotalk auth list
+
+# Switch the current account
+agent-kakaotalk auth use <account-id>
+
+# Use a specific account for any command
+agent-kakaotalk chat list --account <account-id>
+agent-kakaotalk message send <chat-id> "Hello" --account <account-id>
+```
+
+Without `--account`, commands use the current (default) account.
+
+## Commands
+
+### Chat Commands
+
+```bash
+# List all chat rooms (sorted by most recent activity)
+agent-kakaotalk chat list
+agent-kakaotalk chat list --pretty
+agent-kakaotalk chat list --account <account-id>
+
+# Fetch all chats (paginate beyond login snapshot)
+agent-kakaotalk chat list --all
+
+# Search for a chat by display name
+agent-kakaotalk chat list --search "Alice"
+agent-kakaotalk chat list --all --search "project"
+```
+
+Output includes:
+
+- `chat_id` — numeric chat room ID
+- `type` — chat type (1:1, group, open chat)
+- `display_name` — comma-separated member names
+- `active_members` — number of active members
+- `unread_count` — unread message count
+- `last_message` — most recent message preview
+
+### Message Commands
+
+```bash
+# List messages in a chat room
+agent-kakaotalk message list <chat-id>
+agent-kakaotalk message list <chat-id> -n 50
+agent-kakaotalk message list <chat-id> --from <log-id>
+agent-kakaotalk message list <chat-id> --pretty
+
+# Send a text message
+agent-kakaotalk message send <chat-id> "Hello world"
+agent-kakaotalk message send <chat-id> "Hello world" --pretty
+
+# Use a specific account
+agent-kakaotalk message list <chat-id> --account <account-id>
+agent-kakaotalk message send <chat-id> "Hello" --account <account-id>
+```
+
+Each message includes:
+
+- `log_id` — unique message identifier
+- `type` — message type (1 = text, 2 = photo, etc.)
+- `author_id` — sender's user ID
+- `message` — message text content
+- `sent_at` — Unix timestamp (milliseconds)
+
+#### Fetching More Messages
+
+The CLI handles internal pagination automatically. Just increase `-n` to get more messages. Pagination is capped at ~4,000 raw messages (50 pages × 80 per page). If the cap is hit, a warning is printed to stderr and results may be incomplete.
+
+```bash
+# Get latest 20 messages (default)
+agent-kakaotalk message list 9876543210
+
+# Get 50 messages
+agent-kakaotalk message list 9876543210 -n 50
+
+# Get 200 messages
+agent-kakaotalk message list 9876543210 -n 200
+
+# Get messages newer than a known log ID (forward only)
+agent-kakaotalk message list 9876543210 --from 123456789
+```
+
+## Global Options
+
+| Option      | Description                                                 |
+| ----------- | ----------------------------------------------------------- |
+| `--account` | Use a specific KakaoTalk account (default: current account) |
+| `--pretty`  | Human-readable output instead of JSON                       |
+
+## Storage
+
+- Credentials stored in `~/.config/agent-messenger/kakaotalk-credentials.json` (0600 permissions)
+- macOS extraction reads from `~/Library/Containers/com.kakao.KakaoTalkMac/Data/Library/Caches/Cache.db`
+- Windows extraction reads from the registry and `%LocalAppData%\Kakao\login_list.dat`
+
+## Limitations
+
+- `auth extract` requires macOS or Windows (reads from the KakaoTalk desktop app)
+- `auth login` works on any platform (email + password, no desktop app needed)
+- No file upload or download
+- No channel/chat room creation or management
+- No friend list management
+- No reactions or emoji
+- No message editing or deletion
+- No open chat browsing or joining
+- No search across chats
+
+- Plain text messages only (no photos, videos, or rich content)
+- Chat IDs are numeric and not human-readable — use `chat list` to discover them
+
+## Troubleshooting
+
+### `agent-kakaotalk: command not found`
+
+**`agent-kakaotalk` is NOT the npm package name.** The npm package is `agent-messenger`.
+
+```bash
+# If installed globally
+agent-kakaotalk chat list --pretty
+
+# If not installed, use --package
+npx -y --package agent-messenger agent-kakaotalk chat list --pretty
+```
+
+**NEVER run `npx agent-kakaotalk`** without `--package agent-messenger`. It will fail or install a wrong package.
+
+### No credentials found
+
+If `auth extract` fails:
+
+1. Make sure the KakaoTalk desktop app is installed and you're logged in
+2. Run `agent-kakaotalk auth extract --debug` for detailed diagnostics
+3. If extraction still fails, use `agent-kakaotalk auth login` instead (recommended)
+
+### Device slot occupied
+
+If login fails because the tablet slot is occupied:
+
+```bash
+# Option 1: Use the PC slot instead
+agent-kakaotalk auth login --device-type pc --force
+
+# Option 2: Force the tablet slot (kicks existing tablet session)
+agent-kakaotalk auth login --device-type tablet --force
+```
+
+### Passcode verification timeout
+
+If the passcode expires before you confirm on your phone:
+
+1. Run `agent-kakaotalk auth login` again — a new passcode will be generated
+2. Confirm the code on your phone within the time limit
+3. The CLI automatically completes login after confirmation
+
+### Cache.db not found (macOS)
+
+The CLI looks for KakaoTalk's cache at:
+
+```
+~/Library/Containers/com.kakao.KakaoTalkMac/Data/Library/Caches/Cache.db
+```
+
+If this file doesn't exist:
+
+1. Install KakaoTalk from the Mac App Store
+2. Log in and send at least one message (to populate the cache)
+3. Run `agent-kakaotalk auth extract` again
+
+## AI Agent Integration
+
+See [`skills/agent-kakaotalk/`](https://github.com/devxoul/agent-messenger/tree/main/skills/agent-kakaotalk) for:
+
+- Complete skill documentation
+- Common patterns for AI agent workflows