terminal-error-agent — Inline Failure Diagnoser

terminal-error-agent — Inline Failure Diagnoser An architecture diagram generated by Archify. Your terminal · any tab · bash or zsh · Architecture component Your terminal any tab · bash or zsh _tea_preexec() · remembers the command · One shell session · bash or zsh · trap DEBUG · preexec hook _tea_preexec() remembers the command trap DEBUG · preexec hook stderr tee · exec 2> >(tee -a …) · One shell session · bash or zsh · source-time redirect stderr tee exec 2> >(tee -a …) source-time redirect .tea_stderr_<pid>.log · /tmp · per shell PID · One shell session · bash or zsh · last 4 KB only .tea_stderr_<pid>.log /tmp · per shell PID last 4 KB only _tea_precmd() · runs at prompt return · One shell session · bash or zsh · skips exit 0 and 130 _tea_precmd() runs at prompt return skips exit 0 and 130 _tea_analyze() · guard · read · ask Claude · One shell session · bash or zsh · one call per failure _tea_analyze() guard · read · ask Claude one call per failure claude CLI · claude -p · Architecture component · your Claude Code login claude CLI claude -p your Claude Code login every command command stderr tee -a append exit ≠ 0, 130 only while tea on tail -c 4000 claude -p prompt 2-3 sentences 🤖 printed to stderr One shell session · bash or zsh Legend Backend Database Message bus External

Trigger

  • • preexec stores the last command line — bash via `trap … DEBUG`, zsh via add-zsh-hook preexec
  • • precmd reads $? at prompt return and skips 0 and 130, so Ctrl-C never triggers a call
  • • One claude call per failed line: pipelines and && chains analyze only the last simple command

Capture

  • • exec 2> >(tee -a "$_tea_log" >&2) mirrors stderr to /tmp/.tea_stderr_<pid>.log while still showing it
  • • Only the last 4000 bytes are read, then the log is truncated so the next command starts clean
  • • A child that redirects its own stderr (2>/dev/null) never reaches the log — the tee only sees the shell's stream

Guardrails

  • • Off by default: TEA_ENABLED stays 0 until you run `tea on` in that shell — nothing persists between tabs
  • • Silently skips when `claude` is not on PATH, so machines without the CLI are unaffected
  • • Costs ~1-2 s per failure before the next prompt, and a failed claude call prints that error with no retry