Session Mapping Pattern

How Claude Code Sessions Work

• Claude Code stores all sessions locally in ~/.claude/projects/<project-name>/
• Each session is a UUID with a .jsonl file containing the full conversation
• Sessions can be resumed with --resume <session-id>

Chat Platform Integration

Every chat (Telegram, WhatsApp, etc.) maps to a Claude Code session ID. The mapping is stored in a lightweight SQLite table:

chat_platform + chat_id  →  session UUID

Column	Example
platform	telegram / whatsapp
chat_id	123456789
session_id	a462dd58-4b25-4fcd-bf9a-1c71ba812f7f

When a message arrives:

1. Look up session_id for the chat_id
2. Pass it to Claude Code SDK via --resume <session_id>
3. Claude continues the same conversation thread

/newchat deletes the mapping row, so the next message starts a fresh session.

Key Insight

You don’t store conversations yourself — Claude Code already does that. You only store the mapping (a few rows in SQLite).

Telegram Markdown → HTML

Telegram’s bot API only supports a limited HTML subset: <b>, <i>, <code>, <pre>, <s>, <a>, <u>. Claude responds in Markdown, so a formatForTelegram() conversion is needed:

1. Extract and protect code blocks first (so contents aren’t mangled)
2. Convert headings, bold, italic, links, checkboxes, strikethrough
3. Escape &, <, > in text nodes
4. Strip unsupported elements (---, raw HTML)

Source: ClaudeClaw REBUILD_PROMPT.

Open Questions

References

• ClaudeClaw REBUILD_PROMPT — original implementation for Telegram
• FR-022 (Phone Access) — Telegram bot, Phase 2
• FR-023 (Email & WhatsApp) — WhatsApp integration, Phase 3