kmsg

kmsg - KakaoTalk CLI

An unofficial CLI tool that reads and sends KakaoTalk messages using the macOS Accessibility API.

Prerequisites Check

Always check before working:

# 1. 설치 확인
kmsg status

# 2. 미설치 시 → scripts/install.sh 실행
bash <skill-path>/scripts/install.sh

Quick Reference

kmsg status                              # 상태 확인
kmsg chats                               # 채팅 목록
kmsg read "채팅방" --limit 20 --json      # 메시지 읽기 (JSON)
kmsg send "채팅방" "메시지"                # 메시지 전송
kmsg send "채팅방" "메시지" --dry-run      # 전송 테스트 (실제 발송 안 함)

Workflow

0. Verify screen/window context (required)

kmsg Before running, check the following first:

1. Check whether the KakaoTalk main list window ("KakaoTalk") is in the foreground
2. If a chat window is already open, close it (leave only the list window)
3. When finding a target in the list, do not automatically select the first result
4. do not select by position (1st/2nd/3rd) — read the visible chat room name text on screen and select only the row that exactly matches the requested target
5. After entering the target, re-verify that the current window title matches the requested chat room name
6. If it does not match, stop immediately and return to the list

Recommended check command:

kmsg chats --limit 30 --verbose   # 목록/미리보기 확인
kmsg inspect --depth 2            # 현재 포커스 창/목록 구조 확인

1. Reading messages

# 기본 읽기
kmsg read "홍길동" --limit 20

# JSON 출력 (파싱용 - 반드시 --json 플래그 사용)
kmsg read "홍길동" --limit 20 --json

# 창 탐색 실패 시 복구 모드
kmsg read "홍길동" --limit 20 --json --deep-recovery

JSON output structure:

{
  "chat": "홍길동",
  "fetched_at": "2026-02-26T01:23:45.678Z",
  "count": 20,
  "messages": [
    {"author": "홍길동", "time_raw": "00:27", "body": "메시지 내용"}
  ]
}

2. Sending messages

CRITICAL: Always get send confirmation from the user before executing.

# 실제 전송
kmsg send "홍길동" "안녕하세요"

# 테스트 (전송 안 함)
kmsg send "홍길동" "테스트" --dry-run

# 윈도우 유지하며 전송
kmsg send "홍길동" "메시지" --keep-window

3. Debugging

If a problem occurs:

kmsg inspect --window 0 --depth 20       # UI 구조 검사
kmsg read "채팅방" --limit 5 --trace-ax   # AX 트레이싱
kmsg send "채팅방" "test" --trace-ax --dry-run

4. Stabilized workflow for bulk summarization across multiple rooms (by unread)

For bulk tests (e.g., "summarize all 100+ unread rooms"), fix the following order.

1. Return to the KakaoTalk main list window + close open chat windows
2. kmsg inspect --depth 6to save a chat list AX tree snapshot
3. From the AX tree, chat room name + unread count (number/300+) extract
4. Select only rooms at or above the threshold (e.g., >=100, >=300)
5. Only for the selected rooms, kmsg read "방이름" --limit 120~300 --jsonread with
6. After generating the summary, number of detected rooms / number of actually processed roomsreport together

Recommended principles:

• Since the unread badge can fluctuate depending on screen state, recollect inspect on every run
• Count Label Since the value may be the number of participants, use the numeric badge at the bottom of the row for unread (e.g., 105, 300+) as a priority
• To avoid same-name/similar rooms, always exact match of the room name text in the AX rowprocess only with this

Example (threshold selection):

# 1) 스냅샷
kmsg inspect --depth 6 > /tmp/kmsg_inspect.txt

# 2) 파싱 스크립트로 100+ 방 추출 (환경별로 스크립트 재사용 가능)
python3 - <<'PY'
# /tmp/kmsg_inspect.txt를 읽어 "방 이름 + unread"를 추출하는 로컬 파서 작성/실행
# (환경마다 AX 트리 구조가 달라질 수 있으므로 정규식은 현장 보정)
PY

Summary format (recommended):

• Target room / unread count
• Key flow (3 lines)
• Top 3 main topics
• Atmosphere/tone
• One-line conclusion

Safety Rules

1. Always confirm with the user before sending - never send without permission
2. --dry-run first - if in doubt, dry-run first
3. Unofficial tool - excessive use may result in account restrictions
4. Accessibility permission - Must allow kmsg in System Settings > Privacy & Security > Accessibility
5. Window name verification required - After entering the target, immediately stop if the current window title does not match the requested chat room name
6. No re-searching inside the room - Do not perform additional searches/re-searches on the chat room's internal screen; return to the list window and retry
7. Prioritize verifying result row text - Directly check the row text in the search results, and only open it when it exactly matches the requested name (do not click by index)

Sequential Send (sending to multiple recipients)

When sequential sending to multiple people is needed: references/sequential-send.md

• Message templates including salutations, safety rules, failure handling
• Includes a Fallback method that sends directly via AppleScript without kmsg

MCP Integration

To use directly from an agent, refer to the MCP server settings: references/mcp-setup.md

Common Errors

Error	Cause	Solution
KMSG_BIN_NOT_FOUND	kmsg not installed	scripts/install.sh Run
ACCESSIBILITY_PERMISSION_DENIED	Permission not granted	Allow permission in System Settings
KAKAO_WINDOW_UNAVAILABLE	KakaoTalk not running/no window	After launching KakaoTalk, retry, --deep-recovery
CHAT_NOT_FOUND	Chat room search failed	Check the chat room name, --deep-recovery
WINDOW_NOT_READY	Another window is in front/chat window not opened	List window (카카오톡) to the front, clean up open chat windows and retry
SEARCH_MISS	Similar names/open chat search missed	After narrowing the search term, exact name match verify, and if needed have the user open the room first