Claude Code Bridge

Bridge every incoming message to a live, persistent claude CLI process running
in a background tmux session. The user interacts via QQ/Telegram/any channel;
Claude Code responds as if they were typing in a real terminal.

Session State Detection (CRITICAL — CHECK EVERY TURN)

At the start of EVERY incoming message, determine session state:

CODEBLOCK0

• - ✅ Claude Code 会话运行中 → CC mode active, route message to CC
• INLINECODE2 → CC mode off, respond normally
• INLINECODE3 → tell user and await their approval choice

Construct <SESSION_ID> as <channel>_<chat_id> using only [a-zA-Z0-9_].

Routing Logic

CODEBLOCK1

Startup Flow — Working Directory

When the user wants to start Claude Code without specifying a directory:

1. 1. Ask briefly: INLINECODE7
2. Parse the reply:

- User sends a path (e.g. ~/projects/paper) → start ~/projects/paper - User says "沙盒" / "随便" / "临时" / doesn't specify → INLINECODE10

When the user specifies a directory in the startup command itself:

• - "在 ~/Documents/Code 打开cc" → extract the path → INLINECODE11
• "沙盒打开cc" / "沙盒模式启动cc" → INLINECODE12

Do NOT ask if the path is already provided in the command.

Executing Actions

CODEBLOCK2

IMPORTANT — message quoting: Use tmux send-keys -l (literal mode) so
special characters ($, !, \) are sent verbatim. The script handles this
internally; just pass the raw message as argument 3.

CC Slash Commands — Direct Passthrough

CC's own slash commands work by sending them via send:

User says	Forward as
INLINECODE18	INLINECODE19
INLINECODE20

send '/model sonnet' |
| /compact | send '/compact' |
| /cost | send '/cost' |
| /help | send '/help' |
| /clear | send '/clear' |
| /diff | send '/diff' |
| /fast | send '/fast' |
| /vim | send '/vim' |
| /context | send '/context' |
| /export | send '/export' |
| /copy | send '/copy' |
| /rewind | send '/rewind' |
| /fork | send '/fork' |
| /permissions | send '/permissions' |
| /tasks | send '/tasks' |
| /status | send '/status' |
| /stats | send '/stats' |
| /review | send '/review' |
| /theme | send '/theme' |
| /sandbox | send '/sandbox' |
| Any /xxx command | send '/xxx' |

These are NOT OpenClaw commands — forward them verbatim to CC.
All CC slash commands work via passthrough, including ones not listed above.

Handling CC Approval Prompts

When CC encounters a tool it needs permission to run, it shows a TUI selection
menu (arrow-key navigation, not text input). The approve action handles this:

CODEBLOCK3

The user's reply should be interpreted:

• - "y" / "是" / "好" / "1" / "同意" → INLINECODE63
• "2" / "允许" / "一直允许" → INLINECODE64
• "n" / "否" / "不" / "3" / "拒绝" → INLINECODE65
• "取消" / "cancel" → INLINECODE66

Long Tasks & Streaming

For tasks that take a long time (refactoring, writing large codebases):

1. 1. Detect intent: if the user's message implies a large task (e.g. "重构整个项目",

"帮我写一个完整的 XXX"), use --long flag (5-minute timeout)

1. 2. If the output is empty after timeout, use peek to check CC's current state
2. If CC is still working, inform the user: INLINECODE69
3. Then use peek or history to get progress updates

Formatting — Seamless Mode

Goal: make the user feel like they're talking to Claude Code directly.

When CC session is active:

• - Do NOT prefix every reply with 🤖 CC → — just relay CC's output directly
• Only add brief status markers for:

· Session startup / shutdown
· Approval prompts (show the options)
· Errors / timeouts

• - CC's code blocks, file paths, tool output → relay as-is, no reformatting
• Empty output → brief CC 处理中... then try peek after 3s
• Output >3000 chars → show last 2000 chars, note /cc history for full output
• Approval prompt → show options directly, minimal decoration

Error Handling

Situation	Action
INLINECODE76 returns empty	Wait 3s, run peek, relay result
Session not found

Inform user, offer to start | | Session crashed | Detect via status, offer restart | | CC shows error | Relay error verbatim | | Timeout on long task | Inform user, suggest peek or history |

Additional Resources

• - scripts/claude-code-bridge.sh — Full session management (start/send/approve/stop/restart/status/workdir/peek/history)
• references/usage.md — User-facing help text and example conversations