KakaoTalk CLI for AI agents - read and send messages via database + UI automation
# Add to your Claude Code skills
git clone https://github.com/silver-flight-group/kakaocliLast scanned: 6/4/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-06-04T08:21:20.981Z",
"npmAuditRan": true,
"pipAuditRan": true
}No comments yet. Be the first to share your thoughts!
CLI tool for KakaoTalk on macOS — read chats, search messages, send texts, and integrate with AI agents.
macOS용 카카오톡 CLI 도구 — 채팅 읽기, 메시지 검색, 텍스트 전송, AI 에이전트 연동.
[!NOTE] This tool reads KakaoTalk's local database and automates the UI via macOS Accessibility APIs. It does not reverse-engineer the KakaoTalk protocol or call any Kakao APIs. See Disclaimer for details.
kakaocli lets AI agents (Claude Code, Cursor, custom bots) check and send your KakaoTalk messages — something Kakao's official APIs simply can't do.
Kakao's official APIs cannot read chat history, export conversations, or send free-form messages. If you want an AI agent to check your messages, summarize conversations, or reply on your behalf — there's no official way to do it. kakaocli fills that gap by reading the local database and automating the native macOS client.
kakaocli는 AI 에이전트(Claude Code, Cursor, 커스텀 봇)가 카카오톡 메시지를 확인하고 보낼 수 있게 해줍니다 — 카카오 공식 API로는 불가능한 기능입니다.
카카오 공식 API로는 채팅 기록을 읽거나, 대화를 내보내거나, 자유로운 메시지를 보낼 수 없습니다. AI 에이전트가 메시지를 확인하거나, 대화를 요약하거나, 대신 답장하게 하고 싶어도 공식적인 방법이 없습니다. kakaocli는 로컬 데이터베이스를 읽고 네이티브 macOS 클라이언트를 자동화하여 이 부분을 해결합니다.
Option A: Homebrew (recommended)
brew install silver-flight-group/tap/kakaocli
This installs sqlcipher automatically and builds from source (~20 seconds).
Option B: Build from source
brew install sqlcipher
git clone https://github.com/silver-flight-group/kakaocli.git
cd kakaocli
swift build -c release
# Binary is at .build/release/kakaocli
# Either add to PATH or run directly:
.build/release/kakaocli status
# Or use swift run:
swift run kakaocli status
Your terminal app needs two permissions in System Settings > Privacy & Security:
터미널 앱에 다음 두 가지 권한이 필요합니다 (시스템 설정 > 개인정보 보호 및 보안):
[!NOTE] Full Disk Access is required for all commands. Accessibility is only needed for
send,harvest, andinspect.
# Check KakaoTalk installation and permissions
kakaocli status
# Verify database decryption
kakaocli auth
# List your most recent chats
kakaocli chats --limit 10
If auth succeeds, you're all set. All read commands work immediately — no KakaoTalk login or window required.
auth가 성공하면 준비 완료입니다. 모든 읽기 명령은 카카오톡 창 없이도 바로 작동합니다.
# Search across all your messages
kakaocli search "점심"
# Read recent messages from a chat (substring match on name)
kakaocli messages --chat "지수" --since 7d
# Send a message (opens KakaoTalk UI automatically)
kakaocli send "지수" "안녕!"
# Send to self-chat (나와의 채팅) — safe for testing
kakaocli send --me _ "test message"
# Stream new messages as JSON
kakaocli sync --follow
# Run a custom SQL query against the database
kakaocli query "SELECT COUNT(*) FROM NTChatMessage"
[!TIP] Use
--meto send to your self-chat (나와의 채팅) when testing. This is the safest way to verify send functionality.
| Command | Description |
|---------|-------------|
| kakaocli status | Check KakaoTalk installation and permissions |
| kakaocli auth | Verify database decryption |
| kakaocli chats | List chats sorted by last activity |
| kakaocli messages --chat "name" | Show messages from a chat (substring match) |
| kakaocli search "keyword" | Full-text search across all messages |
| kakaocli schema | Dump raw database schema |
| kakaocli query "SQL" | Run read-only SQL against the decrypted database |
All read commands support --json for structured output.
모든 읽기 명령은 --json 옵션으로 구조화된 출력을 지원합니다.
kakaocli send "chat name" "message" # Send to a chat
kakaocli send --me _ "message" # Send to self-chat (나와의 채팅)
kakaocli send --dry-run "name" "msg" # Preview without sending
kakaocli sync --follow # NDJSON stream of new messages
kakaocli sync --follow --interval 1 # Poll every 1 second
kakaocli sync --follow --webhook http://localhost:8080/kakao # POST to webhook
See AGENTS.md for AI agent integration instructions.
kakaocli harvest # Capture display names for all chats
kakaocli harvest --scroll # Also load older message history
kakaocli harvest --scroll --top 20 # Process top 20 most recent chats
kakaocli harvest --dry-run # Preview without changes
The harvest command iterates through your chat list to:
(unknown) in the database)--scroll: open each chat, scroll to top, click "View Previous Chats" to load older messages~/.kakaocli/metadata.jsonChats with unread messages are skipped to avoid marking them as read.
kakaocli login # Store credentials (interactive)
kakaocli login --email user@example.com --password pw # Non-interactive
kakaocli login --status # Check status
kakaocli login --clear # Remove credentials
When you run send, sync, or any command that needs KakaoTalk, the tool automatically launches the app, detects the login screen, fills credentials, and waits for login to complete.
kakaocli is designed to work with AI coding assistants and agents. Every read command outputs structured JSON, and the tool handles KakaoTalk's full lifecycle automatically (launch, login, window management).
Add kakaocli as a skill in your project's CLAUDE.md:
## KakaoTalk Integration
Use `kakaocli` to read and send KakaoTalk messages:
- `kakaocli chats --json` — list all chats
- `kakaocli messages --chat "name" --json` — read messages
- `kakaocli search "keyword" --json` — search messages
- `kakaocli send "name" "message"` — send a message
- `kakaocli send --me _ "message"` — send to self-chat (safe for testing)
Or copy the skill file directly:
# Copy the skill definition to your project
cp skills/kakaocli/SKILL.md /path/to/your/project/.claude/skills/
Claude Code can then read your KakaoTalk messages, search conversations, and send messages on your behalf.
Add to your project rules or .cursorrules:
You have access to kakaocli for KakaoTalk messaging.
Run `kakaocli chats --json` to list chats.
Run `kakaocli messages --chat "name" --since 1d --json` to read messages.
Run `kakaocli send "name" "message"` to send messages.
Always use --me flag when testing: `kakaocli send --me _ "test"`.
Always ask for confirmation before sending messages to other people.
For agents that need to react to incoming messages in real-time:
# Stream new messages as NDJSON (pipe to your agent)
kakaocli sync --follow | your-agent-processor
# Or POST to a webhook endpoint
kakaocli sync --follow --webhook http://localhost:8080/kakao
Each new message is delivered as a JSON object:
{"chatId": 123, "logId": 456, "author": "김지수", "message": "안녕!", "sentAt": "2026-02-20T09:15:00Z"}
A kakaocli skill definition is included for use with OpenClaw or similar skill registries.
See AGENTS.md for detailed integration instructions including credential setup, lifecycle management, and error handling.
kakaocli reads KakaoTalk's local SQLCipher-encrypted database in read-only mode — it never modifies the database. For sending messages and UI interactions, it uses macOS Accessibility APIs (AXUIElement) to automate the native KakaoTalk client.
kakaocli는 카카오톡의 로컬 SQLCipher 암호화 데이터베이스를 읽기 전용 모드로 읽습니다 — 데이터베이스를 절대 수정하지 않습니다. 메시지 전송 및 UI 상호작용에는 macOS 접근성 API(AXUIElement)를 사용하여 네이티브 카카오톡 클라이언트를 자동화합니다.
[!WARNING] macOS only. This tool works exclusively with KakaoTalk for Mac. It does not support Windows, mobile, or web versions.
kakaocli harvest --scroll to trigger loading older history, but this is limited by KakaoTalk's own sync behavior and the Talk Drive Plus paywall.(unknown). The database doesn't always store display names for group chats. Run kakaocli harvest to capture names from the UI.send, sync, and harvest need the KakaoTalk window. kakaocli launches and logs in automatically if credentials are stored.