SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscmux-team-investigate

cmux-team-investigate

General & other

View repository

Updated 10-15 22:15

About this skill

cmux-team-investigate

Overview

Another project (~/git/mado, ~/git/Dear etc., another repository that has already introduced cmux-team) .team/ Standard procedure for investigating under this path.manager.log、traces.db、task-state.json, and correlate the cmux surface screen to isolate the cause.

This skill is Valid only within the worktree of this repository (the cmux-team development repository) This is a developer-oriented skill..claude/skills/ It is under this path and is not included in npm publish or plugin distribution. It cannot be used from Claude Code sessions in other projects.

Prerequisites

  • The target is a cmux-team project running in another workspace, and.team/ it must have this structure
  • The target repository's .team/ は read-only Treat it as such. Do not run write-oriented CLI (create-task, update-task, close-task etc.) with the target CWD
  • If you determine that a fix is needed, file it as a separate task in the appropriate repository (the principle that Master does not write code directly is maintained)

--project-root Use of the flag (recommended, Task 440)

cmux-team The CLI has --project-root <path> A flag is provided, allowing you to read the state of another project without cd.

# read 系（status / agents / events / metrics / trace-task / trace-hooks）は確認不要
cmux-team status --project-root "$TARGET"
cmux-team trace-task <id> --project-root "$TARGET"
cmux-team trace-hooks --project-root "$TARGET" --type SESSION_ENDED --limit 20

If you run a write-oriented command against a project different from cwd, a confirmation prompt appears (in a non-TTY environment it can be skipped with --project-root-confirm or CMUX_TEAM_PROJECT_ROOT_CONFIRM=1 ). Do not use write-oriented commands on the target in an investigation.

The env route (PROJECT_ROOT=<path> cmux-team ...) still works as before, but if the flag is specified, env is ignored. As strict validation, if the path specified by the flag does not exist / does not contain .team/ , it exits 1.

Step 1: Identify the target repository

# パス指定が明確な場合
TARGET=~/git/mado

# surface ID 経由で特定する場合（cmux 上の不審なペインから辿る）
cmux identify --surface <surface-id>
# → caller.workspace_ref からワークスペースのルートを推定し、
#   そこに対応する .team/ を持つリポジトリを TARGET にセット
TARGET=$(cmux identify --surface <surface-id> | jq -r '.caller.workspace_ref')

# .team/ の存在確認（無ければ通常のリポジトリ調査に切り替え）
ls "$TARGET/.team/" || { echo "対象に .team/ が無い → 通常の git log / grep 調査へ"; exit 1; }

workspace_ref is not necessarily the repository path itself, so take the conservative procedure of confirming by the existence of.team/ .

Step 2: Collect logs

# manager.log 末尾
tail -n 200 "$TARGET/.team/logs/manager.log"

# 特定キーワードで grep（タスク ID、conductor、error）
grep -E "task-042|conductor_|error" "$TARGET/.team/logs/manager.log" | tail -n 100

# タスク状態スナップショット
cat "$TARGET/.team/task-state.json" | jq '.tasks | to_entries[] | {id:.key, status:.value.status}'

# Conductor の状態
ls "$TARGET/.team/conductors/"
cat "$TARGET/.team/conductors/conductor-1.json" 2>/dev/null

Step 3: Search the trace DB

The role of the trace DB

traces.db は session index and does not hold conversation content.

traces.db（インデックス）
  └─ task_sessions: session_id, role, surface, task_id, event, worktree_path
       ↓ session_id を使って
Claude Code 生ログ（本体）
  └─ ~/.claude/projects/<project-dir>/<session_id>.jsonl

task_sessions The table has no FTS5 virtual table, and full-text search is not possible.

Note: .team/logs/traces/api-trace.jsonl is the proxy access log (timestamp/method/path/status/bytes only) and does not contain conversation content.

DB query

# 方式 A: 対象リポジトリに cd して cmux-team trace-task を実行
( cd "$TARGET" && cmux-team trace-task <task-id> )

# 方式 B: sqlite3 で直接 readonly 参照（ロック回避のため readonly モード）
sqlite3 "file:$TARGET/.team/traces/traces.db?mode=ro" -readonly \
  "SELECT timestamp, task_id, session_id, role, surface, event FROM task_sessions WHERE task_id='042' ORDER BY id ASC;"

# 方式 C: ロックが掛かっている場合は cp してから読む
cp "$TARGET/.team/traces/traces.db" /tmp/traces-snapshot.db
sqlite3 /tmp/traces-snapshot.db "SELECT * FROM task_sessions WHERE task_id='042';"

Reference the raw log from session_id

DB で session_id Once you obtain , directly open the corresponding Claude Code session file.

# プロジェクトディレクトリ名の変換ルール: パスの / を - に置換し先頭に - を付ける
# 例: /Users/yamamoto/git/mado → -Users-yamamoto-git-mado
SESSION_ID="2577bcfe-2f0e-4dfa-b277-326731acb6ba"
PROJECT_DIR="-Users-yamamoto-git-mado"   # $TARGET のパスから導出
JSONL=~/.claude/projects/$PROJECT_DIR/$SESSION_ID.jsonl

# worktree 内セッションは別ディレクトリに存在する
# 例: /Users/yamamoto/git/mado/.worktrees/task-001-... → -Users-yamamoto-git-mado--worktrees-task-001-...

# tool_use（Bash コマンド）を抽出する
python3 - <<'EOF'
import sys, json
for line in open("$JSONL"):
    obj = json.loads(line)
    if obj.get("type") == "assistant":
        for block in obj.get("message", {}).get("content", []):
            if isinstance(block, dict) and block.get("type") == "tool_use":
                inp = block.get("input", {})
                cmd = inp.get("command", "")
                if cmd:
                    print(cmd[:300])
                    print("---")
EOF

Note — tool_use disappears after compaction: When Claude Code reaches the context limit, it compresses the conversation. After compression, the JSONL retains only assistant In the message text blocks, and tool_use all blocks are lost. Whether compaction has occurred can be judged by the number of lines (a few dozen or fewer) or by whether the tool_use count is zero.

Refer to the hook_signals table — "which hooks actually fired"

task_sessions is the session index, whereashook_signals The table is Raw log of all hook signals received by the Manager daemon (T216 "hook all-send policy"). Whether hook shell → daemon reception was established can be confirmed before the Manager's branch decision (handleMessage), so this is the first table to consult for symptoms such as "Conductor does not return to idle" or "Agent completion is not detected".

Examples of recorded hook types: SESSION_STARTED / SESSION_STOPPED / SESSION_ENDED / SESSION_IDLE / SESSION_CLEAR / AGENT_SPAWNED / SESSION_ASK / CONDUCTOR_DONE。

Schema (skills/cmux-team/manager/trace-store.ts の CREATE TABLE IF NOT EXISTS hook_signals）:

CREATE TABLE hook_signals (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  timestamp TEXT NOT NULL,
  type TEXT NOT NULL,
  surface TEXT,
  pid INTEGER,
  reason TEXT,
  source TEXT,
  question TEXT,
  task_run_id TEXT,
  payload_json TEXT NOT NULL
);
-- index: type / surface / timestamp

Method A: cmux-team trace-hooks subcommand (T217)

When targeting another project, always run in the target CWD.

# id DESC で新しい順に最大 50 件（デフォルト）
( cd "$TARGET" && cmux-team trace-hooks )

# hook type で絞り込み
( cd "$TARGET" && cmux-team trace-hooks --type SESSION_ENDED --limit 20 )

# surface で絞り込み（surface:665 / 665 / C[665] のいずれも受理）
( cd "$TARGET" && cmux-team trace-hooks --surface 'C[665]' )

# task_run_id で絞り込み、JSON 配列として出力
( cd "$TARGET" && cmux-team trace-hooks --task-run task-042-1712345678 --json )

Options: --type <TYPE> / --surface <surface> / --task-run <id> / --limit <N>(default 50, id DESC) / --json. The command implementation is in skills/cmux-team/manager/main.ts の cmdTraceHooks。

Method B: Direct readonly reference via sqlite3

# ある task_run の hook を時系列（古い順）で見る
sqlite3 "file:$TARGET/.team/traces/traces.db?mode=ro" -readonly \
  "SELECT timestamp, type, surface, pid, reason, task_run_id
   FROM hook_signals
   WHERE task_run_id='task-042-1712345678'
   ORDER BY id ASC;"

# ある surface で発火した hook を時系列で見る
sqlite3 "file:$TARGET/.team/traces/traces.db?mode=ro" -readonly \
  "SELECT timestamp, type, reason, source
   FROM hook_signals
   WHERE surface='surface:665'
   ORDER BY id ASC;"

For lock avoidance, use the same ?mode=ro URI or cp snapshot method as for other tables (see "Notes → trace DB locking").

Investigation procedure guidelines

  • Conductor does not return to idle → type IN ('SESSION_IDLE','SESSION_CLEAR','SESSION_ENDED') by target surface and check whether hooks are arriving
  • Agent completion is not detected → type='CONDUCTOR_DONE' or type='SESSION_ENDED' by task_run_id
  • The hook itself is not firing(no rows in hook_signals) → a problem on the hook shell side. Suspect the hook configuration and matcher on the Claude Code side
  • The hook is arriving but the Manager is not reacting → a problem on the Manager's branch decision (handleMessage) side. Cross-check withmanager.log to identify the cause

hook_signals is the raw log before the Manager's filter, so treat it as the primary source for separating "did the hook arrive" from "did the Manager process it correctly".

Step 4: Direct surface reference

When referencing another workspace, always add --workspace (see CLAUDE.md "Notes on using the cmux API").

WS=$(cmux identify --surface <surface-id> | jq -r '.caller.workspace_ref')
cmux read-screen --surface <surface-id> --workspace "$WS"

# ワークスペース全体の状態
cmux list-status --workspace "$WS"
cmux tree --workspace "$WS"

Step 5: Time-series correlation

manager.log timestamps (ISO 8601 with local TZ) as the reference axis and cross-check with the timestamp column in the trace DB.

# manager.log 側
grep "task-042" "$TARGET/.team/logs/manager.log"
# 例: [2026-04-12T10:30:15+09:00] conductor_started conductor=1 task=042

# trace DB 側（同タスクの行を時系列で）
sqlite3 "file:$TARGET/.team/traces/traces.db?mode=ro" -readonly \
  "SELECT timestamp, role, event FROM task_sessions
   WHERE task_id='042' ORDER BY timestamp ASC;"

# 必要ならログと DB を時刻でソートしてマージ確認

Notes

  • No writing: Do not write to the target project's .team/ .create-task / update-task / close-task must not be run in the target CWD. Fix tasks should be filed separately this repository or handed to the owner of the target repository.
  • Continuation of Master responsibilities: Once the cause is identified through investigation, file the fix as a separate task in the appropriate repository with cmux-team create-task . The principle that the Master does not write code directly remains unchanged.
  • trace DB lock: Because the target daemon is opened in WAL mode, write access may conflict. When reading, use the ?mode=ro URI, or cp snapshot.
  • Not distributed: This skill itself is under this repository's .claude/skills/ , and is not included in npm publish or plugin distribution. It cannot be used in Claude Code sessions of other projects.