kmsg Architecture

Overview

kmsg is a Swift 6 executable for macOS 13 and later. It controls KakaoTalk through macOS Accessibility APIs instead of a network protocol.

The primary dependency direction is:

CLI commands
    |
    +-- authentication and command orchestration
    |
    +-- KakaoTalk domain services
    |     +-- chat discovery and identity
    |     +-- window resolution
    |     +-- transcript resolution and parsing
    |
    +-- Accessibility helpers and AX path cache
          |
          +-- AXUIElement / CGEvent / AppKit
                |
                +-- KakaoTalk for macOS

The stdio MCP server is another entry point. It translates MCP tool calls into subprocess invocations of the currently running kmsg executable, then returns structured results to the client.

Components

Data flow

Startup and authentication

1. A command checks Accessibility permission when UI access is required.
2. AuthBootstrap constructs KakaoTalkApp, which launches KakaoTalk when necessary.
3. KakaoTalkAuthenticator checks the current login state.
4. If login is required, it loads encrypted credentials or prompts the user, performs the login, and stores newly entered credentials.

read --background-safe is deliberately different: it constructs KakaoTalkApp(autoLaunch: false) and skips automatic login and foreground UI automation.

Listing chats

1. ChatsCommand selects the visible chat-list window or recovers a usable KakaoTalk window.
2. ChatListScanner locates the chat-list container and extracts row titles and previews.
3. ChatIdentityRegistryStore matches discoveries against local records and assigns synthetic IDs.
4. Results are printed as text or encoded as JSON.

The registry is local state, not a KakaoTalk identifier. A renamed room is treated as a new display identity, and duplicate names receive distinct local records when they can be distinguished from the list.

Resolving a chat

ChatWindowResolver tries progressively more invasive paths:

1. Reuse an existing matching chat window.
2. For a known chat_id, try its associated chat-list row.
3. Search for the recorded or requested display name.
4. When explicitly enabled, perform deeper window recovery.

In background-safe mode only step 1 is allowed. The resolver will not launch, activate, search, open, resize, or close KakaoTalk windows.

Reading messages

1. Resolve a chat window by name or chat_id.
2. MessageContextResolver identifies the input element, chat pane, and transcript root.
3. KakaoTalkTranscriptReader gathers message rows and extracts their semantic fields.
4. ReadCommand prints human-readable output or one JSON document.
5. A transiently opened window is closed unless --keep-window was supplied.

Watching messages

1. Resolve the chat and read snapshots for up to two seconds until the tail stabilizes.
2. Use messages later than the watch start time as the initial eligible state.
3. Poll at a clamped interval between 0.2 and 10 seconds.
4. Compare snapshot overlap to find newly appended messages.
5. Emit human-readable records or one pretty JSON object per event.

Rows without a safe logical timestamp may be suppressed at startup to avoid replaying old messages.

Sending text or images

Text sending resolves the target window, finds and focuses the message input, enters Unicode text through AX/keyboard helpers, and verifies the send action. Image sending places the image on the macOS pasteboard, pastes it into the chat, and handles KakaoTalk's confirmation UI.

Commands close only windows they opened transiently. --keep-window preserves them.

MCP calls

MCP client
    |
    | Content-Length or newline-delimited JSON-RPC
    v
kmsg mcp-server
    |
    | subprocess: current kmsg executable
    +-- kmsg read --json ...
    +-- kmsg send ...
    +-- kmsg send-image ...
    |
    v
structured MCP content and error metadata

The process boundary reuses the same CLI paths as direct operation and prevents the MCP layer from maintaining a second implementation of KakaoTalk automation.

Local state

Credential directories use owner-only 0700 permissions; credential and key files use 0600. Encryption protects the stored representation, but both the ciphertext and its local key remain on the same machine.

AX cache entries use schema validation, a KakaoTalk version/build fingerprint, a root fingerprint, candidate validation, and a seven-day TTL. An invalid or stale entry falls back to discovery and is replaced or removed.

Directory structure

.
├── Package.swift
├── VERSION
├── VERSIONING.md
├── Plugins/
│   └── VersionGenPlugin/
├── Sources/
│   ├── VersionGenTool/
│   └── kmsg/
│       ├── Accessibility/
│       ├── Auth/
│       ├── Commands/
│       ├── KakaoTalk/
│       └── kmsg.swift
├── docs/
│   ├── openclaw.md
│   └── openclaw.mcp.example.json
├── tests/
├── tools/
│   ├── kmsg-mcp.py
│   └── sync_homebrew_tap.py
├── scripts/
│   └── headatever.sh
├── .github/workflows/
│   ├── ci.yml
│   └── release.yml
└── video/

tools/kmsg-mcp.py is a legacy/development reference implementation. The installed integration entry point is the native kmsg mcp-server command. video/ contains promotional Remotion assets and is not part of the CLI runtime.

Design decisions

Accessibility instead of a private protocol

KakaoTalk does not expose an official CLI. kmsg therefore interacts with the same visible application UI a user operates, using Apple's Accessibility APIs.

This avoids implementing or reverse-engineering KakaoTalk's private LOCO protocol. It does not make kmsg an official or risk-free integration: service terms and enforcement remain Kakao's decision.

Swift for a macOS-native executable

The implementation depends directly on AppKit, ApplicationServices, AXUIElement, CGEvent, CryptoKit, and the pasteboard. Swift provides direct access to those frameworks, native distribution, and Objective-C interoperability without an additional runtime.

Bounded discovery with self-healing fast paths

AX hierarchies are expensive and can change between KakaoTalk versions. Discovery methods use limits and node budgets. Successful paths are cached, but every cached result is revalidated before use; stale paths fall back to bounded discovery.

Explicit interaction modes

Normal commands may launch, activate, recover, search, resize, and close windows. Background-safe reads opt into a narrower contract that forbids those operations and succeeds only when a matching chat is already exposed.

Deep recovery is also opt-in for direct CLI commands. Fast paths remain the default to avoid unnecessary relaunch and window manipulation.

Local synthetic chat identity

KakaoTalk's Accessibility tree does not expose a durable public chat ID. kmsg chats therefore generates a local chat_id from normalized names and maintains collision records locally. It improves repeated lookup but is not a remote identifier or a guarantee across machines.

Output-channel separation

Structured command output is written to stdout. AX traces remain on stderr, allowing JSON consumers and MCP subprocesses to parse output without mixing diagnostic logs into payloads.

Version source of truth

The root VERSION file is authoritative. A SwiftPM build-tool plugin validates it and generates BuildVersion during compilation. Release tags use vMAJOR.YYMMDD.PATCH_COUNT; the release workflow verifies that the universal binary reports the same version before publishing it.

Preserved project rationale

The following prose is preserved verbatim from the original Korean README.