Repository navigation
Troubleshooting
Start with tmag doctor. The installation skill includes a
triage table for installation,
plugin approval and pane attachment problems.
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.
- Before an agent's first hook (startup, folder-trust dialogs) it shows as
unknown;tmag waiton 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
workinguntil its next prompt. One interrupted withtmag interruptis idle at once. - The Codex title items are not a stable interface. tmag reads the
thread-iditem 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 doctorthen 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 attachcannot 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
tmaginstalled another way,tmag setupcannot 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
piin 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 apipane that shows no session.