From 7564604c5393551c6bb44f075b89f3ba9245717d Mon Sep 17 00:00:00 2001 From: rootiest Date: Tue, 16 Jun 2026 15:05:41 -0400 Subject: [PATCH 1/3] fix(zellij): repair scrollback logging on shell exit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The zellij wrapper (functions/zellij.fish) rewrote every `zellij` invocation as `zellij options --theme catppuccin-mocha `, which is only valid for launching a new session. This mangled every subcommand, including the `zellij action dump-screen` call inside _zellij_dump_log, so no logs were ever produced. The theme is already set in config.kdl, making the wrapper redundant — remove it. Also harden _zellij_dump_log: - dump-screen takes the file via stdout redirect, not a positional arg (rejected by zellij 0.44) nor --path (server-side write, flaky) - add --ansi to preserve color in the logs - discard empty dumps instead of leaving junk files Document the structural limitation: zellij can only snapshot on a clean shell exit, unlike tmux's continuous pipe-pane stream. Closing a pane or quitting zellij tears down the pane/server before it can be dumped. --- README.md | 7 ++++++- docs/fish-config.index | 1 - docs/fish-config.md | 37 +++++++++++++++++++++++---------- functions/_zellij_dump_log.fish | 7 ++++++- functions/zellij.fish | 19 ----------------- 5 files changed, 38 insertions(+), 33 deletions(-) delete mode 100644 functions/zellij.fish diff --git a/README.md b/README.md index 126d115..659f805 100644 --- a/README.md +++ b/README.md @@ -66,13 +66,18 @@ This config captures terminal output to `~/.terminal_history` (override with |---|---|---| | Kitty scrollback | When a Kitty window/tab closes | `scrollback_.log` | | tmux pane | Continuously while the pane is open (`pipe-pane`) | `tmux_-w-p_.log` | -| zellij pane | Snapshot taken on shell exit (`dump-screen`) | `zellij_-p_.log` | +| zellij pane | Snapshot taken on **clean** shell exit (`dump-screen`) | `zellij_-p_.log` | | `paru` wrapper | Every `paru` invocation | `paru_.log` | | `yay` wrapper | Every `yay` invocation | `yay_.log` | Old logs are pruned automatically to stay within `$SCROLLBACK_HISTORY_MAX_FILES` (default 100) per source, and empty/trivial captures are discarded. +> **zellij caveat:** zellij has no continuous pipe like tmux, so its pane is +> snapshotted only on a clean shell exit (`exit`/Ctrl-D). Closing a pane or +> quitting zellij directly tears down the pane/server before it can be dumped, +> so those sessions are not logged. End with `exit` to guarantee a log. + **These logs can contain secrets** — anything printed to your terminal (command output, file dumps, tokens echoed to stdout) ends up in them. They never leave your machine, but treat `~/.terminal_history` as sensitive. diff --git a/docs/fish-config.index b/docs/fish-config.index index de17cd9..a669335 100644 --- a/docs/fish-config.index +++ b/docs/fish-config.index @@ -155,7 +155,6 @@ joplin=### joplin replay=### replay tmux=### tmux-clean wake-lock=### wake-lock -zellij=### zellij # ── Section 6: Dependency Catalog ──────────────────────────── catalog=# 6. DEPENDENCY CATALOG diff --git a/docs/fish-config.md b/docs/fish-config.md index f9e77dc..dc1d260 100644 --- a/docs/fish-config.md +++ b/docs/fish-config.md @@ -1423,11 +1423,6 @@ Add -i (interactive confirmation) to destructive commands: wake-lock rsync -avz src/ dest/ -### zellij - - Synopsis: zellij [args...] - Launches zellij with the Catppuccin Mocha theme applied. - --- # 6. DEPENDENCY CATALOG @@ -1750,12 +1745,32 @@ SCROLLBACK_HISTORY_MAX_FILES, matching the paru/yay wrapper behaviour. The zellij capture works differently: Zellij has no live output-streaming facility like pipe-pane, so the log is taken as a one-shot snapshot when the -shell exits, via `zellij action dump-screen --full`. A fish_exit handler -(registered whenever $ZELLIJ is set) writes the pane's full scrollback and -then prunes old zellij_*.log files the same way. Because the capture happens -at exit, toggling __fish_config_op_logging takes effect on the next exit with -no restart or sentinel coordination needed — the C5 guard is re-checked when -the handler fires. +shell exits, via `zellij action dump-screen --full --ansi` (the --ansi flag +preserves color). The dump is captured on the fish process's stdout and +written to the log file by fish itself (not via `--path`, which would make the +zellij server write the file). A fish_exit handler (registered whenever +$ZELLIJ is set) writes the pane's full scrollback and then prunes old +zellij_*.log files the same way. Because the capture happens at exit, toggling +__fish_config_op_logging takes effect on the next exit with no restart or +sentinel coordination needed — the C5 guard is re-checked when the handler +fires. + +LIMITATION — zellij capture only fires on a clean shell exit (typing `exit`, +Ctrl-D, or a logout), because that is when the fish_exit handler runs. It does +NOT capture when you close a pane or quit zellij through zellij itself: + + - Closing a pane signals the shell and tears the pane down concurrently, so + even if the handler runs, `dump-screen` may find the pane buffer already + gone. + - Quitting zellij kills the zellij server, and `dump-screen` needs a live + server to read from — there is nothing left to snapshot. + +This is a structural difference from tmux, NOT a bug. tmux streams pane output +to disk continuously via pipe-pane, so whatever was printed is already saved +no matter how the pane dies. Zellij can only snapshot, and the only reliable +snapshot point from the shell is a clean exit. To guarantee a zellij pane is +logged, end the session with `exit` or Ctrl-D rather than zellij's close-pane +or quit actions. The Kitty watcher is managed by the kitty-logging command: it installs a version-marked watcher (fish-config-watcher.py) into the Kitty config directory diff --git a/functions/_zellij_dump_log.fish b/functions/_zellij_dump_log.fish index 3f4e822..05bd1f7 100644 --- a/functions/_zellij_dump_log.fish +++ b/functions/_zellij_dump_log.fish @@ -34,7 +34,12 @@ function _zellij_dump_log --description 'Dump the current Zellij pane scrollback set -l log_file "$log_dir/zellij_"$session"-p"$pane_id"_"$timestamp".log" mkdir -p $log_dir - zellij action dump-screen --full "$log_file" 2>/dev/null + # Dump to STDOUT and let this fish process write the file. `--path` makes the + # zellij *server* write the file (its CWD/permissions, historically flaky); + # capturing STDOUT keeps the write client-side and reliable. Drop the empty + # file if the dump produced nothing (e.g. pane already torn down on exit). + zellij action dump-screen --full --ansi >"$log_file" 2>/dev/null + test -s "$log_file"; or command rm -f "$log_file" _prune_terminal_logs zellij end diff --git a/functions/zellij.fish b/functions/zellij.fish deleted file mode 100644 index e055e5a..0000000 --- a/functions/zellij.fish +++ /dev/null @@ -1,19 +0,0 @@ -# Copyright (C) 2026 Rootiest -# SPDX-License-Identifier: AGPL-3.0-or-later - -# SYNOPSIS -# zellij [args...] -# -# DESCRIPTION -# Launches zellij with the Catppuccin Mocha theme applied via -# --theme catppuccin-mocha. -# -# ARGUMENTS -# args... Arguments forwarded to zellij -# -# EXAMPLE -# zellij -function zellij --wraps='zellij' --description 'alias zellij=zellij options --theme catppuccin-mocha' - command zellij options --theme catppuccin-mocha $argv - -end -- 2.52.0 From 68a9cd17bf0a49c4bbac87edcf03eb60b7eec4e4 Mon Sep 17 00:00:00 2001 From: rootiest Date: Tue, 16 Jun 2026 15:10:40 -0400 Subject: [PATCH 2/3] docs(index): add zellij/tmux logging keywords to help index Point zellij, zellij-logging, tmux-logging, pipe-pane, and dump-screen lookups at the C5 logging section. tmux=tmux-clean stays for the function. --- docs/fish-config.index | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/fish-config.index b/docs/fish-config.index index a669335..cd47c45 100644 --- a/docs/fish-config.index +++ b/docs/fish-config.index @@ -192,6 +192,11 @@ integrations-detail=#### C4 — Terminal and Tool Integration c5=#### C5 — Logging and Capture logging-detail=#### C5 — Logging and Capture logging-sentinel=#### C5 — Logging and Capture +zellij=#### C5 — Logging and Capture +zellij-logging=#### C5 — Logging and Capture +tmux-logging=#### C5 — Logging and Capture +pipe-pane=#### C5 — Logging and Capture +dump-screen=#### C5 — Logging and Capture c6=#### C6 — Greeting and First-Run UI greeting=#### C6 — Greeting and First-Run UI -- 2.52.0 From 1aac43af628ce02e456e75a05f6dd89cd887dec9 Mon Sep 17 00:00:00 2001 From: rootiest Date: Tue, 16 Jun 2026 15:14:40 -0400 Subject: [PATCH 3/3] docs(index): expand help-index coverage and fix stale targets Add tool-name synonyms whose names appear in no heading (so the fallback substring scan can't reach them): eza/exa/lsd, trash, btop, prettyping, duf/dust, kitten, bat. Add integration and topic keywords (zoxide, direnv, venv/virtualenv, wakatime, tailscale, done/notify, pager-hierarchy, shell-aliases, kitty-logging/watcher, agy, antigravity-ide, html/browser, wiki). Fix stale entries pointing at renamed/removed headings: - antigravity -> ### antigravity-resume (### antigravity was removed) - man-page/manpage -> ## As a man page (dropped '(if compiled)') - disambiguate duplicate 'secrets' key: secrets.fish is now secrets-file --- docs/fish-config.index | 44 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 40 insertions(+), 4 deletions(-) diff --git a/docs/fish-config.index b/docs/fish-config.index index cd47c45..14e3c04 100644 --- a/docs/fish-config.index +++ b/docs/fish-config.index @@ -133,7 +133,9 @@ logging=## 5.11 Pager and Logging logs=### logs smart-exit=### smart_exit ai=## 5.12 AI and Developer Tools -antigravity=### antigravity +antigravity=### antigravity-resume +antigravity-ide=### antigravity-ide +agy=### agy claude-cli=### claude claude=### claude-resume claude-docs=### claude-docs @@ -156,6 +158,37 @@ replay=### replay tmux=### tmux-clean wake-lock=### wake-lock +# ── Tool-name synonyms (replacement → shadowed command) ────── +# These tools don't appear in any heading, so the fallback scan can't +# find them; map each to the function that wraps it. +eza=### ls +exa=### ls +lsd=### ls +trash=### rm +btop=### top +prettyping=### ping +duf=### du +dust=### du +kitten=### ssh +bat=### cat + +# ── Tool integrations (Section: Integrations) ──────────────── +zoxide=### Zoxide +z=### Zoxide +direnv=### DirEnv +venv=### Auto Python Venv +virtualenv=### Auto Python Venv +python=### Auto Python Venv +wakatime=### WakaTime +tailscale=### Tailscale +done=### Done Notifications +notifications=### Done Notifications +notify=### Done Notifications +pager-hierarchy=## Pager Hierarchy +shell-aliases=## 4.11 Shell Aliases +kitty-logging=### kitty-logging +watcher=### kitty-logging + # ── Section 6: Dependency Catalog ──────────────────────────── catalog=# 6. DEPENDENCY CATALOG deps-catalog=# 6. DEPENDENCY CATALOG @@ -229,13 +262,16 @@ updating=## Updating # ── Section 10: Personalization ─────────────────────────────── personalization=# 10. PERSONALIZATION personalize=# 10. PERSONALIZATION -secrets=## secrets.fish +secrets-file=## secrets.fish local-config=## local.fish # ── Section 11: Viewing This Manual ────────────────────────── viewing=# 11. VIEWING THIS MANUAL manual=# 11. VIEWING THIS MANUAL ov=## With ov (recommended) -man-page=## As a man page (if compiled) -manpage=## As a man page (if compiled) +man-page=## As a man page +manpage=## As a man page jump=## Jumping to a section +html=## In the browser (HTML) +browser=## In the browser (HTML) +wiki=## As a wiki -- 2.52.0