Skip to content

Troubleshooting

ChrAlpha edited this page Nov 12, 2026 · 6 revisions
🇬🇧English | 🇨🇳中文

Troubleshooting

Start with tmag doctor. The installation skill includes a triage table for installation, plugin approval and pane attachment problems.

Diagnostics

New hook.log entries contain timestamp, source and a fixed failure category, never command output or hook input. A serialized append/rotation keeps the log at 256 KiB; older raw entries survive only until rotation and doctor redacts them. tmag doctor uses one two-second diagnostic budget, bounded host output and owned helper cleanup. It reports the first current metadata fault and location, last hook contact from at most 32 directory entries, recent metadata-only hook failures and existing event-log validation. Incomplete probes remain unknown; historical failures alone do not establish current failure. Log validation keeps its existing recovery behavior; doctor does not certify a forensic history. It also names the tmux options that silently undo what tmag shows, with the line that restores each: monitor-bell off leaves alerts without a window flag, and allow-set-title off (tmux 3.5 and later) keeps a Codex pane from showing its thread. tmag changes neither.

Known limitations

  • Before an agent's first hook (startup, folder-trust dialogs) it shows as unknown; tmag wait on its pane lasts until it reports.
  • Claude Code does not report a turn interrupted with Esc, and may not send its idle notification afterwards either: a session interrupted in its terminal shows working until its next prompt. One interrupted with tmag interrupt is idle at once.
  • The Codex title items are not a stable interface. tmag reads the thread-id item of Codex 0.167: the thread id's first 29 characters and ..., in any position. If a Codex release changes it, Codex panes stop showing their sessions; tmag doctor then warns while Codex sessions run in the daemon and no Codex pane shows one.
  • A Codex thread exists before its first prompt, but its hooks start with that prompt: until then the pane shows unknown.
  • Codex reports a daemon thread's end about a minute after its last terminal closes, when the daemon unloads it.
  • A pane running claude attach cannot be proven to show its background session (see Sessions and panes).
  • Pi and oh-my-pi have no hooks; tmag's extension reads the events of Pi 1.5.0 and oh-my-pi 18.18.6, which other releases may change. Their packages come from the tmux plugin's directory: with a tmag installed another way, tmag setup cannot connect them, and removing the tmux plugin before them leaves the agents warning about a missing package.
  • A Pi session shows blocked (question) for any dialog an extension opens during a turn, a permission gate included: Pi does not tell which it is.
  • Pi names its process pi in every mode. Run by another program in a pane, an editor's say, it reports its mode and runs as a service, but the pane is still listed as a pi pane that shows no session.

Clone this wiki locally