Logs and Diagnostics

Logs & Diagnostics

When debugging unexpected behavior, plugin crashes, or RPC communication issues, Tuim provides several logging and diagnostic layers.

---

1. Locating Log Files

Tuim logs its frontend reactor, RPC traffic errors, and widget lifecycle events into its isolated state directory.

Finding the Active Log Path

1. Launch Tuim.
2. Press F1 → Settings → About.
3. Inspect the Log path row:

   ~/.local/share/tuim/tuim.log
   

Inspecting Neovim Internal Messages

To view messages and errors emitted by the embedded Neovim processes:

• In Normal mode, type :messages and press Enter.
• Uncaught Lua errors, plugin notices, and LSP notifications are recorded in Neovim's internal message buffer.

---

2. Inspecting Log Output from the Terminal

You can monitor Tuim's log in real-time from a separate terminal window:

tail -f ~/.local/share/tuim/tuim.log

Log entries are prefixed with standard severity levels for easy filtering:

• [ERROR]: Fatal errors, RPC pipe failures, or unrecoverable worker errors.
• [WARN]: Non-fatal issues (e.g. missing clipboard tool, theme fallbacks, unrecognized terminal features).
• [INFO]: Application lifecycle transitions, mode switches, and theme updates.
• [DEBUG]: Verbose dispatch traces and differential redraw metrics.

---

3. Running Diagnostic Scripts

Tuim includes self-contained diagnostic scripts in the repository:

Test Runtime Environment

Verifies that Neovim 0.12+, Tree-sitter parsers, and the default Zig syntax queries load cleanly:

python3 tests/default_runtime.py

Smoke Test Bundled Plugins

Verifies that lazy.nvim, telescope, mason, blink.cmp, and alpha-nvim load without syntax errors in an isolated XDG sandbox:

scripts/plugin_smoke.sh

---

Next Steps

If you need to report an issue, read how to use the built-in reporter in In-App Bug Reporting.