openkakao-cli AGENTS.md

AI Agent Integration Guide

openkakao-cli is designed for AI agent integration. All commands support --json for structured output.

Safety Model

LOCO write operations (send, delete, edit, react) are disabled by default to prevent account bans.

Safe commands (always available, no server contact)

# Read chats from local KakaoTalk database (SQLCipher, no network)
openkakao-cli local-chats --json
openkakao-cli local-read <chat_id> -n 30 --json
openkakao-cli local-search "keyword" --json
openkakao-cli local-schema

# Preview actions without executing
openkakao-cli send 123 "message" --dry-run --json
openkakao-cli delete 123 456 --dry-run --json

Safe commands (REST API, lower risk)

openkakao-cli chats --json
openkakao-cli read <chat_id> --rest --json
openkakao-cli friends --json
openkakao-cli me --json
openkakao-cli doctor --json

Risky commands (require opt-in)

These require allow_loco_write = true in ~/.config/openkakao/config.toml:

openkakao-cli send <chat_id> "message" -y --json
openkakao-cli send --me "test" -y --json    # Send to memo chat
openkakao-cli delete <chat_id> <log_id> -y --json
openkakao-cli edit <chat_id> <log_id> "new" -y --json
openkakao-cli react <chat_id> <log_id> --json

Unattended Mode

For fully non-interactive operation:

openkakao-cli --unattended --allow-non-interactive-send send <chat_id> "msg" -y --json

Or configure in ~/.config/openkakao/config.toml:

[mode]
unattended = true

[send]
allow_non_interactive = true

[safety]
allow_loco_write = true
min_unattended_send_interval_secs = 10

Recommended Agent Workflow

1. Read with local-chats / local-read (zero risk)
2. Preview with --dry-run before any write
3. Execute only after user confirmation
4. Prefer --me flag for testing sends

JSON Output

All commands with --json return structured JSON to stdout. Diagnostic messages go to stderr.

# List chats
openkakao-cli local-chats --json
# Returns: [{"chat_id": 123, "chat_type": 0, "chat_name": "...", ...}]

# Read messages
openkakao-cli local-read 123 --json
# Returns: [{"log_id": 456, "chat_id": 123, "sender_name": "...", "message": "...", ...}]

# Dry-run
openkakao-cli send 123 "hello" --dry-run --json
# Returns: {"dry_run": true, "action": "send", "chat_id": 123, "message": "..."}