kaku-runtime

kaku-runtime

Kaku terminal pane control and multi-session runtime management.

⚠️ Critical rules (violating them causes silent failure)

Rule 1: Submitting must use --no-paste $'\r', cannot use \n

# ✅ 正确 — 触发真实回车键
kaku cli send-text --pane-id $PANE "你的任务"
kaku cli send-text --no-paste --pane-id $PANE $'\r'

# ❌ 错误 — \n 在交互式 CLI（CC/Codex）中不会触发提交
kaku cli send-text --pane-id $PANE "你的任务\n"
kaku cli send-text --no-paste --pane-id $PANE $'\n'

Rule 2: Before starting CC you must unset CLAUDECODE

# ✅ 正确
kaku cli send-text --pane-id $PANE "unset CLAUDECODE && claude --dangerously-skip-permissions"
kaku cli send-text --no-paste --pane-id $PANE $'\r'

# ❌ 错误 — 嵌套 session 会报错退出
kaku cli send-text --pane-id $PANE "claude --dangerously-skip-permissions"

Rule 3: To create a pane use split-pane, not spawn

# ✅ 正确 — 挂在现有窗口，pane 不会消失
PANE=$(kaku cli split-pane --pane-id $PARENT --bottom --percent 65 --cwd $DIR -- zsh -l)

# ❌ 错误 — spawn 的 pane 在命令退出后消失
kaku cli spawn --cwd $DIR -- zsh -l

---

1. Pane basic operations

# 查看所有 pane（输出列：WINID TABID PANEID WORKSPACE SIZE TITLE CWD）
kaku cli list

# 拆分 pane（返回新 pane ID）
# 方向标志：--bottom / --top / --left / --right（--horizontal 等同 --right）
PANE=$(kaku cli split-pane --pane-id $PARENT --bottom --percent 65 --cwd $DIR -- zsh -l)

# 注入文本（不提交，bracketed-paste 模式）
kaku cli send-text --pane-id $PANE "文本内容"

# 提交（⚠️ $'\r' 不是 $'\n'）
kaku cli send-text --no-paste --pane-id $PANE $'\r'

# 注入并提交（shell 命令）
kaku cli send-text --pane-id $PANE "ls -la"
kaku cli send-text --no-paste --pane-id $PANE $'\r'

# 读取屏幕（当前可见区域）
kaku cli get-text --pane-id $PANE | tail -20

# 读取滚动历史（负数 = 向上滚动，例如 -100 表示 100 行前）
kaku cli get-text --pane-id $PANE --start-line -100

# 聚焦 / 关闭
kaku cli activate-pane --pane-id $PANE
kaku cli kill-pane --pane-id $PANE

# 设置 tab 标题（用 --pane-id 通过 pane 找到所在 tab）
kaku cli set-tab-title --pane-id $PANE "任务名称"
# 或直接指定 tab ID
kaku cli set-tab-title --tab-id $TAB "任务名称"

---

2. Layout presets (one-click multi-pane)

# 四方格 2×2 — 新独立窗口（推荐：不与用户当前窗口重叠）
eval $(bash scripts/kaku/layout.sh 4grid --new-window --cwd $DIR \
  | grep -E "TOP_RIGHT|BOT_LEFT|BOT_RIGHT" \
  | awk '{print "export "$0}')

# 四方格 — 当前窗口新 tab
eval $(bash scripts/kaku/layout.sh 4grid --new-tab --cwd $DIR \
  | grep -E "TOP_RIGHT|BOT_LEFT|BOT_RIGHT" \
  | awk '{print "export "$0}')

# 四方格 — 从指定 pane 分裂（用于已有 pane 的场景）
eval $(bash scripts/kaku/layout.sh 4grid --pane-id $P --cwd $DIR \
  | grep -E "TOP_RIGHT|BOT_LEFT|BOT_RIGHT" \
  | awk '{print "export "$0}')

# 其他预置
bash scripts/kaku/layout.sh 2h   --new-window --cwd $DIR  # 上下两行，新窗口
bash scripts/kaku/layout.sh 2v   --pane-id $P --cwd $DIR  # 左右两列
bash scripts/kaku/layout.sh 3col --pane-id $P --cwd $DIR  # 左中右
bash scripts/kaku/layout.sh 1+2  --pane-id $P --cwd $DIR  # 主+底部双监控

---

3. Send text + auto enter (done in one line)

# ✅ 推荐：用 send.sh wrapper，自动追加 Enter
bash scripts/kaku/send.sh --pane-id $PANE "你的命令"

# 等效的两步写法（老写法，不推荐，容易漏 $'\r'）
kaku cli send-text --pane-id $PANE "你的命令"
kaku cli send-text --no-paste --pane-id $PANE $'\r'

# 只注入不回车（粘贴到 CC 输入框，等待手动 submit）
bash scripts/kaku/send.sh --pane-id $PANE --no-submit "待补充的内容"

---

4. Start Claude Code (two ways)

Way A: via Runtime API (recommended, fully automatic)

The LLM only needs one API call; all steps (split pane / unset CLAUDECODE / wait for CC to start / inject goal / enter) are all done automatically:

⚠️ parent_pane_id is a required field, omitting it returns 400 Bad Request. Use -1 to mean "only create the session record, do not start a CC pane" (for debugging/testing). Use an actual pane ID (such as $KAKU_PANE_ID) to mean split out a CC sub-pane next to that pane and start CC.

# 通过 HTTP API（:9090）— parent_pane_id 必传
curl -s -X POST http://localhost:9090/api/runtime/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "member": "claude_code",
    "goal": "你的任务描述",
    "work_dir": "/path/to/project",
    "parent_pane_id": 25
  }'
# 返回：{"id":"rs-xxx","state":"running",...}
# ❌ 错误：省略 parent_pane_id → 400 Bad Request

# 或通过 CLI（等价）
alex runtime session start \
  --member claude_code \
  --goal "你的任务描述" \
  --work-dir . \
  --parent-pane-id $KAKU_PANE_ID

Way B: launch-cc.sh (done in one line, recommended for manual scenarios)

# 一行启动 CC：split pane + env + unset + claude + 注入 goal + Enter
PANE=$(bash scripts/kaku/launch-cc.sh \
  --parent-pane $KAKU_PARENT_PANE \
  --goal "你的任务描述" \
  --work-dir /path/to/project)
echo "CC started in pane $PANE"

Way C: step-by-step manual kaku CLI (for debugging only)

# Step 0: 确保 CC hooks 已注册（幂等，可重复执行）
# 这一步保证 notify_runtime.sh 在 ~/.claude/settings.json 中注册，
# 即使不走 runtime API，CC 的每次工具调用也能上报到 runtime bus。
bash scripts/cc_hooks/notify_runtime.sh --ensure-registered

# Step 1: 拆分 pane
PANE=$(kaku cli split-pane --pane-id $PARENT --bottom --percent 70 --cwd $WORKDIR -- zsh -l)

# Step 2: 设置 runtime 环境变量（如有已知 session ID 则填入）
bash scripts/kaku/send.sh --pane-id $PANE \
  "export RUNTIME_SESSION_ID=<id> RUNTIME_HOOKS_URL=http://localhost:9090"

# Step 3: 启动 CC（注意：unset 不加斜线，是 bash 内建命令）
# ✅ 正确：unset CLAUDECODE
# ❌ 错误：/unset CLAUDECODE（/unset 是路径，bash 找不到）
bash scripts/kaku/send.sh --pane-id $PANE \
  "unset CLAUDECODE && claude --dangerously-skip-permissions"

# Step 4: 等待 CC 欢迎界面（约 3s）
sleep 3

# Step 5: 注入目标并回车
bash scripts/kaku/send.sh --pane-id $PANE "你的任务描述"

Quick diagnosis(check hooks status):

bash scripts/cc_hooks/notify_runtime.sh --ensure-registered
cat ~/.claude/settings.json | jq '.hooks | keys'

---

4. Start Codex

PANE=$(kaku cli split-pane --pane-id $PARENT --bottom --percent 65 --cwd $WORKDIR -- zsh -l)
kaku cli send-text --pane-id $PANE "codex exec --full-auto -- '你的任务'"
kaku cli send-text --no-paste --pane-id $PANE $'\r'

---

5. Runtime Session lifecycle

# 启动 session（CC 在新 pane 中运行）— 两种等价方式
# CLI
alex runtime session start \
  --member claude_code \
  --goal "任务描述" \
  --work-dir . \
  --parent-pane-id $KAKU_PANE_ID

# HTTP API（:9090）
curl -s -X POST http://localhost:9090/api/runtime/sessions \
  -H "Content-Type: application/json" \
  -d '{"member":"claude_code","goal":"任务描述","work_dir":".","parent_pane_id":25}'

# 列出所有 session
alex runtime session list
curl -s http://localhost:9090/api/runtime/sessions | jq .

# 只看运行中
alex runtime session list --state running

# 查看 session 详情（JSON）
alex runtime session status <session-id>
curl -s http://localhost:9090/api/runtime/sessions/<id> | jq .

# 注入文本（解封 stalled session）
alex runtime session inject --id <id> --message "请继续"

# 停止 session
alex runtime session stop --id <id>

Environment variables:

• KAKU_PANE_ID — automatically passes in --parent-pane-id
• KAKU_STORE_DIR — persistence directory (default ~/.kaku/sessions）

---

6. Detect CC completion status

# 轮询直到 bash $ 提示符出现（CC 退出信号）
# macOS bash 提示符格式：hostname:dir user$  或  user@host dir %
while true; do
  LAST=$(kaku cli get-text --pane-id $PANE | tail -3)
  if echo "$LAST" | grep -qE '\$\s*$|%\s*$|bash-[0-9]'; then
    echo "CC session ended"
    break
  fi
  sleep 3
done

CC screen status characteristics:

• ❯ — waiting for input (needs_input)
• ⏺ lines at the beginning scrolling — currently executing (heartbeat)
• bash $ or zsh % prompt at the end — CC process has exited (completed/failed)

Note: macOS bash prompt is in the hostname:dir user$ format, not a bare ^$. Use \$\s*$ to match end of line $(bash) or %\s*$ to match the zsh prompt.

---

7. Event monitoring

# 实时监控所有 session 事件
tail -f ~/.kaku/sessions/*.events.jsonl | jq -r '"\(.type) \(.session_id)"'

# 查看单个 session 历史
cat ~/.kaku/sessions/<id>.events.jsonl | jq .

# 筛选 stall 事件
cat ~/.kaku/sessions/<id>.events.jsonl | jq 'select(.type == "stalled")'

---

Recommended workflow (four-pane grid + two sessions)

# 1. 四方格布局
KAKU_PANE_ID=$KAKU_PANE_ID bash scripts/kaku/layout.sh 4grid --cwd .
# TL=当前 TR=12 BL=13 BR=14

# 2. 右上角跑 CC session
alex runtime session start --member claude_code \
  --goal "分析代码结构" --work-dir . --parent-pane-id 12

# 3. 右下角跑第二个 session
alex runtime session start --member codex \
  --goal "实现分析结果" --work-dir . --parent-pane-id 14

# 4. 左下角监控事件
kaku cli send-text --pane-id 13 \
  "tail -f ~/.kaku/sessions/*.events.jsonl | jq -r '.type + \" \" + .session_id'"
kaku cli send-text --no-paste --pane-id 13 $'\r'