Terminal Recovery คู่มือเรียกใช้งาน Claude บน iTerm / tmux · กรณีเปิดครั้งแรก · หลุด session · iTerm รีสตาร์ต · เครื่อง reboot

Operations · Recovery Guide

Operational runbook — ทำตามตามลำดับในหน้านี้เวลาหลุด session หรือกลับมาทำงานต่อ. ไม่ใช่ runtime · ไม่ใช่ production system · เป็นเอกสารอ้างอิงสำหรับทีมและเจ้าของโปรเจกต์. ห้ามไว้ใจ memory ของ terminal มากกว่า repo state + SYNC.md.

Purpose หน้านี้สำหรับอะไร · เมื่อไรใช้ · ใครใช้

TH อะไร: คู่มือเรียก Claude บน iTerm / tmux · สำหรับ Session A (super app dev).
เมื่อไร: ตอนเริ่มวันใหม่ · หลุดจาก terminal · เปิด iTerm ใหม่ · restart เครื่อง · หรือไม่แน่ใจว่าต้องทำอะไรก่อน.
ใคร: ทุกคนที่เข้ามาทำงานต่อในโปรเจกต์นี้ · ไม่จำกัดแค่เจ้าของเครื่อง · ทีมใหม่อ่านได้ทันที.

EN What: Recovery runbook for running Claude on iTerm / tmux · scoped to Session A (super app dev).
When: Start of day · dropped terminal · fresh iTerm · machine reboot · or unsure what to do first.
Who: Any team member resuming work on this repo · not just the original operator · readable by onboarding engineer.

Recovery Priority Order · อ่านและตรวจตามลำดับนี้

Repo state check pending changes + last commit before doing anything else git status · git log --oneline -10
SYNC.md source of truth for what each session did last · cross-session handoff .claude/SYNC.md
README entry-level orientation for KB and project structure docs/kb/README.md
Document Index registered docs · canonical refs · routes docs/document_index.json
Changelog B-owned phase log · latest_phase + detailed entries docs/kb/data/changelog.json
Claude resume continue prior Claude conversation if one exists claude --resume
tmux convenience persistent terminal pane · reconnect across windows but NOT across reboots tmux ls · tmux attach -t claude_tt

1. Standard Startup Flow เปิดงานครั้งแรกของวัน

เริ่มจาก 0 · เครื่องเพิ่งเปิด · ยังไม่มี session อะไรอยู่.

# 1. เข้า repo cd /Users/KOD/projects/Thailand-Together # 2. (optional แต่แนะนำ) เปิด tmux session ชื่อ claude_tt # เพื่อกัน session หลุดเวลาปิด iTerm window tmux new -s claude_tt # 3. เริ่ม Claude claude

Tip

ถ้าใช้ tmux ครั้งแรก · กด Ctrl-b แล้ว d เพื่อ detach (ออกจาก session แต่ session ยังรันอยู่). ปิด iTerm ได้โดย session ไม่ตาย.

2. Reattach Flow กลับเข้า session เดิมที่ detach ไว้

เคยเปิด session claude_tt ไว้แล้ว · ต้องการกลับเข้ามา.

# 1. ดู session ที่มีอยู่ tmux ls # ผลลัพธ์ตัวอย่าง: # claude_tt: 1 windows (created Thu Apr 18 09:12:33 2026) # 2. เข้ากลับ session เดิม tmux attach -t claude_tt # 3. ถ้า Claude ยังรันอยู่ในนั้น · ใช้ต่อได้เลย # 4. ถ้า Claude หลุดไปแล้ว · รัน claude --resume claude --resume

Shortcut

ถ้ามี session เดียวชื่อ claude_tt ใช้คำสั่งย่อ tmux a ได้เลย · ไม่ต้องระบุ -t.

3. Recovery after Restart / Reload iTerm รีสตาร์ต · เครื่อง reboot · session หาย

กรณีซับซ้อนที่สุด · ต้องสมมุติว่าอะไรก็ไม่เหลือใน memory · ต้องอ่าน repo + SYNC + changelog ก่อนลงมือ.

# 1. เข้า repo · ตรวจสถานะ cd /Users/KOD/projects/Thailand-Together git status git log --oneline -10 # 2. ดู SYNC.md entry ล่าสุด (ทั้ง Session A + B) tail -100 .claude/SYNC.md # 3. ตรวจว่า B มี phase ใหม่หรือไม่ python3 -c "import json; d=json.load(open('docs/kb/data/changelog.json')); print('latest_phase =', d.get('latest_phase'))" # 4. pull latest (กัน drift กับ origin) git pull --ff-only # 5. เปิด tmux · เข้า session เดิมถ้ามี · สร้างใหม่ถ้าไม่มี tmux ls tmux attach -t claude_tt || tmux new -s claude_tt # 6. เริ่ม Claude พร้อม --resume ถ้าเคยมี session ค้างไว้ claude --resume

Warn

หลัง machine restart · tmux session หายทั้งหมด. ต้องสร้างใหม่ · session เดิมก่อน reboot ไม่มีทางได้คืน. เรื่อยๆ ที่ทำมา ให้ดูจาก git log + SYNC.md แทน.

Danger

อย่า assume Claude จำงานที่ทำไว้ได้. claude --resume คืน context conversation แค่บางส่วน · ถ้างานค้างกลาง operation (เช่น แก้ไฟล์ แต่ยังไม่ commit) ให้ตรวจจาก git status ก่อน.

4. Recovery Source of Truth ไฟล์ที่ต้องอ่านก่อน · ลำดับชัดเจน

ทั้งหมดนี้เป็น source of truth · อย่าคาดเดาจาก terminal memory เพียงอย่างเดียว.

File	Owner	Why read	Quick command
.claude/SYNC.md	A + B (shared)	Cross-session handoff · what each session did last · notes to the other session	`tail -80 .claude/SYNC.md`
docs/kb/README.md	B-owned	Orientation for KB structure · routes · categories · dev conventions	`head -80 docs/kb/README.md`
docs/document_index.json	B-owned	All registered docs · canonical refs · route maps · phase linkage	`python3 -c "import json; d=json.load(open('docs/document_index.json')); print(d.get('updated_at'))"`
docs/kb/data/changelog.json	B-owned	Detailed phase-by-phase log · `latest_phase` · entries · files_updated	`python3 -c "import json; d=json.load(open('docs/kb/data/changelog.json')); print(d['latest_phase'])"`
git log / git status	Repo state	Actual code state · uncommitted changes · commit history · untracked files	`git status; git log --oneline -10`

5. Minimal Command Blocks ก้อนคำสั่งสั้น · copy ไปใช้ได้เลย

A · First-time start

cd /Users/KOD/projects/Thailand-Together tmux new -s claude_tt claude

B · Reattach (session exists)

tmux ls tmux attach -t claude_tt

C · Reload / after restart

cd /Users/KOD/projects/Thailand-Together git status git log --oneline -10 tmux ls tmux attach -t claude_tt || tmux new -s claude_tt claude --resume

D · Repo health check (one-liner)

# ครอบทุกอย่างใน quick scan · ไม่เปลี่ยน state cd /Users/KOD/projects/Thailand-Together && \ echo "=== GIT ===" && git status --short && git log --oneline -5 && \ echo "=== SYNC (top 30) ===" && head -30 .claude/SYNC.md && \ echo "=== PHASE ===" && python3 -c "import json; d=json.load(open('docs/kb/data/changelog.json')); print(d['latest_phase'][:120])" && \ echo "=== TMUX ===" && tmux ls 2>/dev/null || echo "no sessions"

6. Operational Rules กฎที่ต้องทำทุกครั้ง

Update .claude/SYNC.md after every meaningful change. ทุก commit ที่เปลี่ยน structure ต้องมี SYNC entry · ทีมข้าม session ต้องตามได้
Commit + push after each work unit. อย่าทิ้ง uncommitted changes ค้างไว้ยาว · ถ้าหลุด · งานไม่กลับ
Trust repo state + SYNC more than terminal memory. terminal ตายได้ · repo + SYNC คือ source of truth เดียว
Do not rely on tmux alone. tmux ตายเมื่อ reboot · ไม่ใช่ persistence
Claude --resume is best-effort. ถ้า conversation ยาวมาก · อาจไม่คืนครบ · ตรวจ git log + SYNC ประกอบ
Respect ownership. A ห้ามแก้ docs/kb/* (B-owned) · B ห้ามแก้ docs/*.html non-KB · per CLAUDE.md Multi-Session Protocol
Read SYNC first · write SYNC last. รอบการทำงานเดี่ยว = อ่าน SYNC → ทำงาน → commit → append SYNC

7. Honest Notes / Limitations สิ่งที่ tmux และ Claude ทำไม่ได้

tmux ช่วย: คง terminal session ไว้ตอนปิด iTerm window · reconnect จาก window ใหม่ · แยก windows ภายใน session เดียว.

Limit

tmux ไม่ช่วย: เมื่อเครื่อง reboot · kill process · OS update · crash · battery out. session ทั้งหมดหาย · ไม่มีทางกู้เฉพาะ tmux.

Limit

claude --resume ไม่ใช่ full session restore. Claude คืน conversation context ล่าสุดเท่าที่ข้อมูลยังอยู่ · ไม่คืน pending edits · ไม่คืน untracked files · ไม่คืน in-flight tool calls.

Ground truth

Real recovery depends on: git status · git log · .claude/SYNC.md · B's changelog.json. ทั้งหมดนี้คือสิ่งเดียวที่ยืนยันได้ว่างานทำถึงไหน · ไม่ใช่ memory ของ terminal หรือของ Claude.

8. Quick Reference · "What to do if..." ถาม/ตอบ · กรณีจริง

ถ้า tmux session ชื่อ claude_tt มีอยู่If tmux session exists

รัน tmux attach -t claude_tt · เข้า session เดิมได้ทันที · ถ้า Claude ยังรันให้ใช้ต่อ · ถ้าหลุด รัน claude --resume

ถ้า tmux session ไม่มีIf tmux session missing

สร้างใหม่: tmux new -s claude_tt แล้วรัน claude --resume · งานที่ผ่านมากู้จาก git log + SYNC.md

ถ้า repo มี uncommitted changesIf repo has uncommitted changes

รัน git status · git diff เพื่อดู · ตัดสินใจ commit (ถ้าเสร็จ) หรือ git stash (ถ้ายังไม่พร้อม) · อย่าทิ้งไว้ยาว

ถ้า Claude session ไม่ชัดว่าทำถึงไหนIf Claude session state unclear

อ่าน .claude/SYNC.md (Session A head) · git log --oneline -10 · แล้วสั่ง Claude "อ่าน SYNC แล้วสรุปว่าทำถึงไหน"

ถ้าต้องการ resume ใช้งานปลอดภัยSafe resume flow

ลำดับ: cd repo → git pull → git status → tail SYNC.md → tmux attach หรือ new → claude --resume → สั่งให้ Claude อ่าน SYNC อีกครั้งก่อนลงมือ

ถ้า B มี phase ใหม่ระหว่างทำงาน AIf B committed new phase while A was working

รัน git pull --ff-only · ถ้า conflict ให้ stop และดู SYNC · ห้ามแก้ไฟล์ B-owned · ถ้าจำเป็นต้อง coord ให้เขียน REQ ใน SYNC.md

ถ้าต้อง handoff ให้คนอื่นต่อIf handoff to another person

Append SYNC entry ก่อน: งานที่ทำ · commit hash · next step · known gotchas · commit + push · แจ้งให้คนรับต่ออ่าน SYNC head ก่อน

ถ้าเครื่อง reboot กลางงานIf machine reboot mid-work

ยอมรับ: tmux หาย · Claude process หาย · Run Section 3 (Recovery after Restart) · ถ้ามี uncommitted work ค้าง → check git stash list · อาจเคย stash ไว้

ถ้าไม่แน่ใจเลยว่าต้องทำอะไรIf totally unsure

ทำ Repo Health Check one-liner จาก Section 5D · รันแล้วอ่าน output · จะเห็น git state + SYNC + B phase + tmux status รวดเดียว

9. Priority Order Summary สรุปลำดับย้ำอีกครั้ง

Repo state — git status · git log --oneline -10
SYNC.md — tail -80 .claude/SYNC.md
KB README — orientation · only when onboarding or unsure
document_index.json — when need full doc list
changelog.json — when need to see B phase detail
claude --resume — to continue prior conversation
tmux — convenience layer · not source of truth

ถ้าต้องเลือกอ่านแค่ 2 ไฟล์ · อ่าน git log + SYNC.md ก่อน. อย่างอื่นรออ่านทีหลังได้.

Terminal Recovery Guide · v1.0 · Session A · A-owned · operational runbook ← Planning hub · IA Governance ↗