local-chats / local-read / local-search / local-schema

Zero server contact

All local-db commands read the encrypted KakaoTalk SQLite database directly on your Mac. No network requests are made, so there is zero risk of account detection or suspension.

Unreliable on current KakaoTalk builds

The key-derivation formula below has drifted from what recent KakaoTalk macOS builds actually use, so decrypting the database currently fails even when the user ID and device UUID are recovered correctly. For login-free reading right now, use ax-read instead — it scrapes the open chat window via the Accessibility API rather than the database.

How it works

KakaoTalk for macOS stores a SQLCipher-encrypted SQLite database locally. OpenKakao derives the decryption key from your device UUID and Kakao user ID using PBKDF2-HMAC-SHA256, then opens the database in read-only mode.

Requirements:

KakaoTalk.app installed and logged in on this Mac
The local database file exists (created automatically by KakaoTalk)
Full Disk Access is not required — the file is in the app's container

local-chats

List chat rooms from the local database.

openkakao-cli local-chats [OPTIONS]

Flag	Description
`-n, --limit <N>`	Max chats to return (default: 50)
`--json`	Output as JSON (global flag)

# List recent chats
openkakao-cli local-chats

# JSON output for agent consumption
openkakao-cli local-chats --json

local-read

Read messages from a specific chat room.

openkakao-cli local-read <chat_id> [OPTIONS]

Flag	Description
`-n, --count <N>`	Max messages to return (default: 30)
`--since <YYYY-MM-DD>`	Only messages after this date
`--json`	Output as JSON (global flag)

# Read last 30 messages
openkakao-cli local-read 900000000000001

# Read messages since a date
openkakao-cli local-read 900000000000001 --since 2025-01-01

# JSON output
openkakao-cli local-read 900000000000001 --json

Local cache is limited

KakaoTalk only caches recent messages locally (typically 1–4 per chat). For full history, use read via LOCO or REST.

local-search

Search message text across all chats in the local database.

openkakao-cli local-search <query> [OPTIONS]

Flag	Description
`-n, --count <N>`	Max results (default: 20)
`--json`	Output as JSON (global flag)

openkakao-cli local-search "배포"
openkakao-cli local-search "meeting" --json

local-schema

Dump the table schema of the local KakaoTalk database. Useful for debugging and protocol research.

openkakao-cli local-schema
openkakao-cli local-schema --json

When to use local-db vs LOCO/REST

Scenario	Recommended
Quick check of recent messages	`local-read`
Agent reading chats without risk	`local-chats` + `local-read`
Full message history	`read` (LOCO)
Token expired, need to read	`local-read` (works offline)
Search across all chats	`local-search`
Protocol research	`local-schema`

Diagnostics

Run doctor to check if the local database is accessible:

openkakao-cli doctor --json

doctor reports the platform UUID, the recovered Kakao user ID, and the resolved database path. To recover the user ID it inspects the KakaoTalk preferences plist using several strategies in order, from cheapest to most expensive — the last is a bounded SHA-512 pre-image search that stops after a short time budget, so doctor never hangs even when the user ID cannot be recovered on a given KakaoTalk build.

KakaoTalk 26.x

Newer KakaoTalk macOS builds (26.x) stopped writing some of the plist keys earlier versions used. v1.2.3 adds compatible discovery paths for these builds. If doctor still cannot resolve the user ID or database path, set OPENKAKAO_CLI_DEBUG=1 and re-run to see which strategy was attempted.

The output includes a Local DB (SQLCipher) check that verifies UUID extraction, user ID, file existence, and decryption.