KakaoTalk

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:

Quick Start

# 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.

# 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.

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

# 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

# Check auth status
agent-kakaotalk auth status

# Remove stored credentials
agent-kakaotalk auth logout
agent-kakaotalk auth logout <account-id>

Commands

Chat Commands

# List all chat rooms (sorted by most recent activity)
agent-kakaotalk chat list
agent-kakaotalk chat list --pretty

# 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

# 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

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:

# 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

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
• No multi-account switching (single account at a time)
• 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.

# 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:

# 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/ for:

• Complete skill documentation
• Common patterns for AI agent workflows