diff --git a/README.md b/README.md
index 08cf56e..07653b5 100644
--- a/README.md
+++ b/README.md
@@ -30,23 +30,24 @@ This config layers on top of the CachyOS base Fish configuration and adds:
- **Smart CLI wrappers** that prefer modern tools (`eza`, `bat`, `btop`, `dust`, `prettyping`) with graceful fallbacks
- **Auto Python venv** activation on directory change (direnv-aware)
- **Kitty terminal** deep integration for splits, tabs, and SSH
-- **Automatic session logging** — terminal scrollback, multiplexer panes (tmux/zellij), and AUR-helper output are captured to `~/.terminal_history` (see the caution below and [Session Logging](#session-logging))
+- **Optional session logging** — terminal scrollback, multiplexer panes (tmux/zellij), and AUR-helper output can be captured to `~/.terminal_history`; **off by default**, opt in when you want it (see the caution below and [Session Logging](#session-logging))
- **AI workflow** helpers for Claude and Antigravity session management
- **WakaTime** shell activity tracking
- **Opt-out toggles** for every opinionated component — see [Minimal Mode](#minimal-mode)
> [!CAUTION]
-> **This configuration logs your terminal sessions to disk by default.**
-> Out of the box it silently captures terminal output to `~/.terminal_history`:
-> Kitty scrollback when a window closes, live tmux pane streams, zellij pane
-> snapshots on exit, and full `paru`/`yay` output. These logs can contain
-> command output, file contents, and anything else printed to your terminal.
-> Nothing is sent off your machine, but the files persist locally until pruned.
+> **This configuration *can* log your terminal sessions to disk.** Logging is
+> **off by default** — but once enabled it silently captures terminal output to
+> `~/.terminal_history`: Kitty scrollback when a window closes, live tmux pane
+> streams, zellij pane snapshots on exit, and full `paru`/`yay` output. These
+> logs can contain command output, file contents, and anything else printed to
+> your terminal. Nothing is sent off your machine, but the files persist
+> locally until pruned.
>
-> To turn all logging off, set the C5 category variable:
+> To turn logging on, set the C5 category variable:
>
> ```fish
-> set -U __fish_config_op_logging off
+> set -U __fish_config_op_logging on
> ```
>
> Or run **`config-settings`** for an interactive menu to flip logging (and any
@@ -60,9 +61,10 @@ This config layers on top of the CachyOS base Fish configuration and adds:
## Session Logging
-This config captures terminal output to `~/.terminal_history` (override with
+This config can capture terminal output to `~/.terminal_history` (override with
`$SCROLLBACK_HISTORY_DIR`) so you can search back through past sessions. It is
-**on by default**. Five sources feed it:
+**off by default** — opt in with `set -U __fish_config_op_logging on`. Once
+enabled, five sources feed it:
| Source | When it captures | Log file |
|---|---|---|
@@ -84,21 +86,26 @@ Old logs are pruned automatically to stay within `$SCROLLBACK_HISTORY_MAX_FILES`
output, file dumps, tokens echoed to stdout) ends up in them. They never leave
your machine, but treat `~/.terminal_history` as sensitive.
-Disable all of it with a single universal variable:
+All of it is controlled by a single universal variable:
```fish
-set -U __fish_config_op_logging off # disable; takes effect in every open shell
-set -Ue __fish_config_op_logging # re-enable (erase the override)
+set -U __fish_config_op_logging on # enable; takes effect in every open shell
+set -U __fish_config_op_logging off # disable again
+set -Ue __fish_config_op_logging # erase — back to the default (off)
```
+Unlike the other categories, C5 is opt-in: an unset variable means off, and
+`__fish_config_opinionated` cannot turn it on for you.
+
Prefer an interactive interface? Run **`config-settings`** for a full-screen
picker that flips logging — and every other opinionated category — on or off
per session or universally, without memorizing variable names.
-Disabling also removes the generated `paru`/`yay` log wrappers and tells the
-Kitty watcher to skip capture via a sentinel file — no shell or terminal
-restart required. Logging is category **C5** in [Minimal Mode](#minimal-mode);
-`set -U __fish_config_opinionated 0` turns it off along with everything else.
+Disabling (or leaving it unset) also removes the generated `paru`/`yay` log
+wrappers and tells the Kitty watcher to skip capture via a sentinel file — no
+shell or terminal restart required. Logging is category **C5** in
+[Minimal Mode](#minimal-mode); `set -U __fish_config_opinionated 0` keeps it
+off along with everything else.
The Kitty scrollback capture is provided by a watcher script that fish-config can
install and manage for you. Inside Kitty, if it isn't set up yet, you'll see a
@@ -113,8 +120,9 @@ one-time-per-session reminder. Manage it with:
`install` adds a clearly-marked managed block to `kitty.conf` and comments out
any conflicting `watcher` line. It affects **new** Kitty windows (existing
-windows keep their current watcher until restarted). Disabling C5 logging makes
-the watcher inert without uninstalling it.
+windows keep their current watcher until restarted). With C5 logging off the
+watcher is inert without needing to be uninstalled, and the reminder stays
+silent until you enable logging.
---
@@ -269,7 +277,7 @@ To opt out, set `__fish_user_dots_symlink` to a falsy value (or toggle **Dots li
## Minimal Mode
-Everything opinionated in this config — command shadows, startup side-effects, key and environment overrides, terminal integrations, logging, and the first-run greeting — is active by default but can be switched off.
+Everything opinionated in this config — command shadows, startup side-effects, key and environment overrides, terminal integrations, and the first-run greeting — is active by default but can be switched off. Logging (C5) is the exception: it is **opt-in**, off until you explicitly enable it.
> **The easy way — `config-settings`:** Run `config-settings` for an interactive TUI that manages settings across four pages — **Universal** and **Session** (the opinionated category toggles below, persistent or per-shell), **Sponge** (history-scrubbing: delay, exit codes, purge-on-exit, and extra sensitive variable names), and **Paths** (scrollback log dir, max files, and the user-dots path) — without typing a single variable name. Navigate with the arrow keys (or `h`/`j`/`k`/`l`); toggle rows step OFF ← DEFAULT → ON, value rows edit inline with `Enter` and clear with `←`. `Tab`/`Shift-Tab` cycle pages and `q` quits. Changes apply instantly. The panel auto-sizes to your terminal width (four tiers from 52- to 78-wide with a 6-column margin), centers itself horizontally, and redraws within ~0.3 s of a resize.
@@ -281,9 +289,9 @@ If you'd rather set them by hand, each category is controlled by a universal var
| `__fish_config_op_autoexec` | Startup side-effects: Fisher bootstrap, theme apply, `paru`/`yay` wrapper generation, auto venv activation, WakaTime hook, auto-pull background fast-forward |
| `__fish_config_op_overrides` | Vi mode, `exit`→`smart_exit`, `$PAGER`/`$MANPAGER`/`$CDPATH`/`XDG`/`PATH`, bang-bang history expansion, autopair, puffer, Starship prompt, theme colors |
| `__fish_config_op_integrations` | Kitty/WezTerm window abbreviations, `done` notifications, `spwin`/`tab`/`split`, `hist`, `logs`, `upgrade`, WakaTime |
-| `__fish_config_op_logging` | Scrollback capture on exit, tmux `pipe-pane` pane logging, zellij `dump-screen` capture on exit, `paru`/`yay` AUR log wrappers, Kitty watcher capture (sentinel-file coordinated) |
+| `__fish_config_op_logging` | **Opt-in — off unless explicitly enabled.** Scrollback capture on exit, tmux `pipe-pane` pane logging, zellij `dump-screen` capture on exit, `paru`/`yay` AUR log wrappers, Kitty watcher capture (sentinel-file coordinated) |
| `__fish_config_op_greeting` | Per-session `fish_greeting` (suppresses distro greetings such as CachyOS fastfetch by overriding with an empty function); first-run welcome banner |
-| `__fish_config_opinionated` | Master switch — all six categories at once |
+| `__fish_config_opinionated` | Master switch — disables all six categories at once (it is a master *off* switch; it cannot enable opt-in C5 logging) |
Set any of them to a falsy value (`0`, `false`, `no`, `off`, `n`) to disable; erase the variable to re-enable. An explicit per-category truthy value overrides a falsy master switch, so you can disable everything with `__fish_config_opinionated=0` and selectively re-enable individual categories:
@@ -298,6 +306,9 @@ set -U __fish_config_op_aliases off
set -U __fish_config_opinionated 0
set -U __fish_config_op_greeting 1
+# Opt in to session logging (C5 is off by default)
+set -U __fish_config_op_logging on
+
# Back to full flavor
set -Ue __fish_config_opinionated
set -Ue __fish_config_op_greeting
diff --git a/config.fish b/config.fish
index 503f389..c635c93 100644
--- a/config.fish
+++ b/config.fish
@@ -15,8 +15,11 @@
# __fish_config_op_overrides C3 — key bindings, env, prompt overrides
# __fish_config_op_integrations C4 — terminal/tool coupling
# __fish_config_op_logging C5 — scrollback capture / AUR log wrappers
+# (opt-in: unset means OFF)
# __fish_config_op_greeting C6 — per-session greeting / first-run welcome
# Example: set -U __fish_config_op_aliases off (erase to re-enable)
+# C5 is the one exception: it defaults to disabled and needs an explicit
+# truthy value — set -U __fish_config_op_logging on
# ──────────────────────── Source CachyOS configs ────────────────────────
if test -f /usr/share/cachyos-fish-config/cachyos-config.fish
diff --git a/docs/fish-config.index b/docs/fish-config.index
index ffe4ac7..af2a5fc 100644
--- a/docs/fish-config.index
+++ b/docs/fish-config.index
@@ -296,7 +296,8 @@ uninstall=## Uninstalling and Reverting to Backup
revert=## Uninstalling and Reverting to Backup
fish-version=## Fish Version Requirement
version-req=## Fish Version Requirement
-disable-logging=## Disable Session Logging
+disable-logging=## Enable or Disable Session Logging
+enable-logging=## Enable or Disable Session Logging
disable-greeting=## Change or Disable the Greeting
change-greeting=## Change or Disable the Greeting
secrets-trouble=## Secrets and Machine-Local Configuration
diff --git a/docs/fish-config.md b/docs/fish-config.md
index 961ca58..c90af60 100644
--- a/docs/fish-config.md
+++ b/docs/fish-config.md
@@ -32,21 +32,23 @@ A production-grade Fish shell configuration targeting Fish 4.x. It provides:
- Drop-in replacements for common Unix tools (ls, cat, rm, du, ping, less)
- Deep Kitty and WezTerm terminal integration: tab/window/pane management from
the command line
-- Automatic session logging: terminal scrollback, tmux/zellij panes, and
- paru/yay output captured to ~/.terminal_history (on by default; see below)
+- Optional session logging: terminal scrollback, tmux/zellij panes, and
+ paru/yay output captured to ~/.terminal_history (off by default; see below)
- Automatic Python virtualenv activation on directory change
- Cross-platform package management via pkg and fish-deps
- AI scaffolding helpers for Claude Code and Antigravity
- Catppuccin Mocha color theme throughout
-CAUTION: **SESSION LOGGING IS ON BY DEFAULT**
-This configuration silently records terminal output to `~/.terminal_history`:
-Kitty scrollback on window close, live tmux pane streams, zellij pane
-snapshots on exit, and full paru/yay output. These logs can contain command
-output, file contents, and secrets printed to the terminal. Nothing leaves
-your machine, but the files persist locally.
-- Disable all logging with: `set -U __fish_config_op_logging off`
+CAUTION: **SESSION LOGGING IS OPT-IN**
+Once enabled, this configuration *can* silently record terminal output to
+`~/.terminal_history`: Kitty scrollback on window close, live tmux pane
+streams, zellij pane snapshots on exit, and full paru/yay output. These logs
+can contain command output, file contents, and secrets printed to the
+terminal. Nothing leaves your machine, but the files persist locally. Logging
+is off unless you turn it on.
+- Enable all logging with: `set -U __fish_config_op_logging on`
- Prefer a menu? Run the interactive picker: `config-settings`
+- Turn it back off with: `set -U __fish_config_op_logging off` (or erase the variable)
- See C5 — Logging and Capture for the full breakdown.
The configuration uses a structured file tree:
@@ -130,7 +132,7 @@ The configuration uses a structured file tree:
11. Troubleshooting
11.1 Uninstalling and Reverting to Backup
11.2 Fish Version Requirement
- 11.3 Disable Session Logging
+ 11.3 Enable or Disable Session Logging
11.4 Change or Disable the Greeting
11.5 Secrets and Machine-Local Configuration
11.6 Tool Init Does Nothing (Return Sentinel)
@@ -2565,12 +2567,18 @@ Every opinionated piece of this config is active by default but can be
switched off through six category opt-out variables, each evaluated via
__fish_variable_check. Set a variable to any falsy value (0, false, no,
off, n) to disable its category; erase it or set a truthy value (1, true,
-yes, on, y) to re-enable. Unset means enabled.
+yes, on, y) to re-enable. Unset means enabled — except for C5 logging, which
+is opt-in (see below).
An explicit per-category truthy value takes precedence over the master
switch: setting __fish_config_opinionated=0 disables all unset categories,
but a category with an explicit truthy value remains enabled regardless.
+C5 (logging) is the one exception to "unset means enabled". Because it
+writes terminal output to disk, it is opt-in: unset means disabled, and the
+master switch cannot enable it. Only an explicit truthy value turns logging
+on.
+
Variable Disables
────────────────────────────────────────
__fish_config_op_aliases Command shadows and flag injection:
@@ -2595,10 +2603,11 @@ but a category with an explicit truthy value remains enabled regardless.
WezTerm window abbreviations, done
notifications, spwin/tab/split,
hist, logs, upgrade, WakaTime
- __fish_config_op_logging Logging & capture: scrollback
- capture on exit, paru/yay AUR log
- wrappers, Kitty watcher capture;
- sentinel file coordinates
+ __fish_config_op_logging Logging & capture (OPT-IN — this one
+ is off unless explicitly enabled):
+ scrollback capture on exit, paru/yay
+ AUR log wrappers, Kitty watcher
+ capture; sentinel file coordinates
cross-process state
__fish_config_op_greeting Greeting & first-run UI: per-session
fish_greeting override (defines empty
@@ -2612,10 +2621,13 @@ Examples:
# Disable command shadows only (rm becomes plain rm again):
set -U __fish_config_op_aliases off
+ # Turn session logging on (opt-in; off until you do this):
+ set -U __fish_config_op_logging on
+
# Full minimal mode — disable all six categories at once:
set -U __fish_config_opinionated 0
- # Re-enable everything:
+ # Re-enable everything (except C5 logging, which stays opt-in):
set -Ue __fish_config_opinionated
# Minimal mode but keep the greeting:
@@ -2769,8 +2781,16 @@ silently failing.
#### C5 — Logging and Capture
-Five components capture shell output to disk. Disabling
-__fish_config_op_logging skips all capture and removes the logging wrappers.
+Five components capture shell output to disk. Unlike every other category,
+C5 is opt-in: it stays off until __fish_config_op_logging is set to an
+explicit truthy value, and a truthy master switch does not enable it. While
+it is off, all capture is skipped and the logging wrappers are removed.
+
+ # Turn it on (persistently, in every shell):
+ set -U __fish_config_op_logging on
+
+ # Turn it back off:
+ set -U __fish_config_op_logging off # or: set -Ue __fish_config_op_logging
Component What it captures
───────────────────────────────────────────────────────────────────────────
@@ -2827,8 +2847,10 @@ The Kitty watcher is managed by the kitty-logging command: it symlinks the
watcher (fish-config-watcher.py) into the Kitty config directory and wires it
into kitty.conf via a managed block. Inside Kitty, a non-blocking
per-session reminder points first-time users at `kitty-logging install` until
-they install or run `kitty-logging dismiss`. Install affects new Kitty windows
-only; runtime disable is still handled by the .logging_disabled sentinel.
+they install or run `kitty-logging dismiss`; the reminder is itself gated on
+C5, so it stays silent until you enable logging. Install affects new Kitty
+windows only; runtime disable is still handled by the .logging_disabled
+sentinel.
Logging coordination via sentinel file
@@ -2837,7 +2859,11 @@ out-of-process components (the Kitty watcher and all running shells):
~/.config/fish/.logging_disabled
-Disabling __fish_config_op_logging:
+Because C5 is off by default, the sentinel is present on a fresh install —
+the startup sync in conf.d/logging-events.fish reconciles it on every shell
+start, so it appears without any action on your part.
+
+Disabling __fish_config_op_logging (or leaving it unset):
1. Creates the sentinel immediately in every open shell.
2. Removes ~/.local/bin/paru and ~/.local/bin/yay logging wrappers;
bare /usr/bin/paru and /usr/bin/yay are used instead.
@@ -2846,7 +2872,7 @@ Disabling __fish_config_op_logging:
4. smart_exit stops saving scrollback logs.
5. Stops tmux pipe-pane capture in every open fish shell inside tmux.
-Re-enabling __fish_config_op_logging:
+Enabling __fish_config_op_logging:
1. Removes the sentinel in every open shell.
2. Regenerates paru/yay logging wrappers in ~/.local/bin/.
3. Kitty watcher resumes capture on the next session exit.
@@ -3198,22 +3224,25 @@ Upgrading Fish by distribution:
For other systems or building from source, see https://fishshell.com.
-## Disable Session Logging
+## Enable or Disable Session Logging
-Disable all logging and capture (scrollback, tmux/zellij pane logs, AUR
-helper wrappers, Kitty watcher):
+Session logging is opt-in: it is off until you turn it on. To enable all
+logging and capture (scrollback, tmux/zellij pane logs, AUR helper wrappers,
+Kitty watcher):
- set -U __fish_config_op_logging off
+ set -U __fish_config_op_logging on
Or toggle it interactively: run `config-settings` and flip the Logging row.
+Disable it again — either an explicit falsy value or erasing the variable
+returns you to the default off state:
+
+ set -U __fish_config_op_logging off
+ set -Ue __fish_config_op_logging
+
This takes effect immediately in all running shells — no restart needed. The
sentinel file, wrapper removal, and pipe-pane teardown happen automatically.
-Re-enable:
-
- set -Ue __fish_config_op_logging
-
See C5 — Logging and Capture for the full component breakdown.
## Change or Disable the Greeting
@@ -3345,7 +3374,7 @@ Disable a single category:
set -U __fish_config_op_autoexec off # C2
set -U __fish_config_op_overrides off # C3
set -U __fish_config_op_integrations off # C4
- set -U __fish_config_op_logging off # C5
+ set -U __fish_config_op_logging off # C5 (already off by default)
set -U __fish_config_op_greeting off # C6
Keep one category active under a master disable:
diff --git a/docs/manual/00-table-of-contents.md b/docs/manual/00-table-of-contents.md
index a376e5f..d79409c 100644
--- a/docs/manual/00-table-of-contents.md
+++ b/docs/manual/00-table-of-contents.md
@@ -45,7 +45,7 @@ sidebar:
11. Troubleshooting
11.1 Uninstalling and Reverting to Backup
11.2 Fish Version Requirement
- 11.3 Disable Session Logging
+ 11.3 Enable or Disable Session Logging
11.4 Change or Disable the Greeting
11.5 Secrets and Machine-Local Configuration
11.6 Tool Init Does Nothing (Return Sentinel)
diff --git a/docs/manual/07-customization.md b/docs/manual/07-customization.md
index d56093a..3074a2f 100644
--- a/docs/manual/07-customization.md
+++ b/docs/manual/07-customization.md
@@ -62,12 +62,18 @@ Every opinionated piece of this config is active by default but can be
switched off through six category opt-out variables, each evaluated via
__fish_variable_check. Set a variable to any falsy value (0, false, no,
off, n) to disable its category; erase it or set a truthy value (1, true,
-yes, on, y) to re-enable. Unset means enabled.
+yes, on, y) to re-enable. Unset means enabled — except for C5 logging, which
+is opt-in (see below).
An explicit per-category truthy value takes precedence over the master
switch: setting __fish_config_opinionated=0 disables all unset categories,
but a category with an explicit truthy value remains enabled regardless.
+C5 (logging) is the one exception to "unset means enabled". Because it
+writes terminal output to disk, it is opt-in: unset means disabled, and the
+master switch cannot enable it. Only an explicit truthy value turns logging
+on.
+
Variable Disables
────────────────────────────────────────
__fish_config_op_aliases Command shadows and flag injection:
@@ -92,10 +98,11 @@ but a category with an explicit truthy value remains enabled regardless.
WezTerm window abbreviations, done
notifications, spwin/tab/split,
hist, logs, upgrade, WakaTime
- __fish_config_op_logging Logging & capture: scrollback
- capture on exit, paru/yay AUR log
- wrappers, Kitty watcher capture;
- sentinel file coordinates
+ __fish_config_op_logging Logging & capture (OPT-IN — this one
+ is off unless explicitly enabled):
+ scrollback capture on exit, paru/yay
+ AUR log wrappers, Kitty watcher
+ capture; sentinel file coordinates
cross-process state
__fish_config_op_greeting Greeting & first-run UI: per-session
fish_greeting override (defines empty
@@ -109,10 +116,13 @@ Examples:
# Disable command shadows only (rm becomes plain rm again):
set -U __fish_config_op_aliases off
+ # Turn session logging on (opt-in; off until you do this):
+ set -U __fish_config_op_logging on
+
# Full minimal mode — disable all six categories at once:
set -U __fish_config_opinionated 0
- # Re-enable everything:
+ # Re-enable everything (except C5 logging, which stays opt-in):
set -Ue __fish_config_opinionated
# Minimal mode but keep the greeting:
@@ -266,8 +276,16 @@ silently failing.
#### C5 — Logging and Capture
-Five components capture shell output to disk. Disabling
-__fish_config_op_logging skips all capture and removes the logging wrappers.
+Five components capture shell output to disk. Unlike every other category,
+C5 is opt-in: it stays off until __fish_config_op_logging is set to an
+explicit truthy value, and a truthy master switch does not enable it. While
+it is off, all capture is skipped and the logging wrappers are removed.
+
+ # Turn it on (persistently, in every shell):
+ set -U __fish_config_op_logging on
+
+ # Turn it back off:
+ set -U __fish_config_op_logging off # or: set -Ue __fish_config_op_logging
Component What it captures
───────────────────────────────────────────────────────────────────────────
@@ -324,8 +342,10 @@ The Kitty watcher is managed by the kitty-logging command: it symlinks the
watcher (fish-config-watcher.py) into the Kitty config directory and wires it
into kitty.conf via a managed block. Inside Kitty, a non-blocking
per-session reminder points first-time users at `kitty-logging install` until
-they install or run `kitty-logging dismiss`. Install affects new Kitty windows
-only; runtime disable is still handled by the .logging_disabled sentinel.
+they install or run `kitty-logging dismiss`; the reminder is itself gated on
+C5, so it stays silent until you enable logging. Install affects new Kitty
+windows only; runtime disable is still handled by the .logging_disabled
+sentinel.
Logging coordination via sentinel file
@@ -334,7 +354,11 @@ out-of-process components (the Kitty watcher and all running shells):
~/.config/fish/.logging_disabled
-Disabling __fish_config_op_logging:
+Because C5 is off by default, the sentinel is present on a fresh install —
+the startup sync in conf.d/logging-events.fish reconciles it on every shell
+start, so it appears without any action on your part.
+
+Disabling __fish_config_op_logging (or leaving it unset):
1. Creates the sentinel immediately in every open shell.
2. Removes ~/.local/bin/paru and ~/.local/bin/yay logging wrappers;
bare /usr/bin/paru and /usr/bin/yay are used instead.
@@ -343,7 +367,7 @@ Disabling __fish_config_op_logging:
4. smart_exit stops saving scrollback logs.
5. Stops tmux pipe-pane capture in every open fish shell inside tmux.
-Re-enabling __fish_config_op_logging:
+Enabling __fish_config_op_logging:
1. Removes the sentinel in every open shell.
2. Regenerates paru/yay logging wrappers in ~/.local/bin/.
3. Kitty watcher resumes capture on the next session exit.
diff --git a/docs/manual/11-troubleshooting.md b/docs/manual/11-troubleshooting.md
index ac7af8a..3523954 100644
--- a/docs/manual/11-troubleshooting.md
+++ b/docs/manual/11-troubleshooting.md
@@ -75,22 +75,25 @@ Upgrading Fish by distribution:
For other systems or building from source, see https://fishshell.com.
-## Disable Session Logging
+## Enable or Disable Session Logging
-Disable all logging and capture (scrollback, tmux/zellij pane logs, AUR
-helper wrappers, Kitty watcher):
+Session logging is opt-in: it is off until you turn it on. To enable all
+logging and capture (scrollback, tmux/zellij pane logs, AUR helper wrappers,
+Kitty watcher):
- set -U __fish_config_op_logging off
+ set -U __fish_config_op_logging on
Or toggle it interactively: run `config-settings` and flip the Logging row.
+Disable it again — either an explicit falsy value or erasing the variable
+returns you to the default off state:
+
+ set -U __fish_config_op_logging off
+ set -Ue __fish_config_op_logging
+
This takes effect immediately in all running shells — no restart needed. The
sentinel file, wrapper removal, and pipe-pane teardown happen automatically.
-Re-enable:
-
- set -Ue __fish_config_op_logging
-
See [C5 — Logging and Capture](/07-customization/#c5-logging-and-capture) for the full component breakdown.
## Change or Disable the Greeting
@@ -222,7 +225,7 @@ Disable a single category:
set -U __fish_config_op_autoexec off # C2
set -U __fish_config_op_overrides off # C3
set -U __fish_config_op_integrations off # C4
- set -U __fish_config_op_logging off # C5
+ set -U __fish_config_op_logging off # C5 (already off by default)
set -U __fish_config_op_greeting off # C6
Keep one category active under a master disable:
diff --git a/docs/manual/index.md b/docs/manual/index.md
index 7f98275..747738a 100644
--- a/docs/manual/index.md
+++ b/docs/manual/index.md
@@ -17,8 +17,8 @@ A production-grade Fish shell configuration targeting Fish 4.x. It provides:
- Drop-in replacements for common Unix tools (ls, cat, rm, du, ping, less)
- Deep Kitty and WezTerm terminal integration: tab/window/pane management from
the command line
-- Automatic session logging: terminal scrollback, tmux/zellij panes, and
- paru/yay output captured to ~/.terminal_history (on by default; see below)
+- Optional session logging: terminal scrollback, tmux/zellij panes, and
+ paru/yay output captured to ~/.terminal_history (off by default; see below)
- Automatic Python virtualenv activation on directory change
- Cross-platform package management via pkg and fish-deps
- AI scaffolding helpers for Claude Code and Antigravity
@@ -27,14 +27,16 @@ A production-grade Fish shell configuration targeting Fish 4.x. It provides:
Install now
Function reference
-CAUTION: **SESSION LOGGING IS ON BY DEFAULT**
-This configuration silently records terminal output to `~/.terminal_history`:
-Kitty scrollback on window close, live tmux pane streams, zellij pane
-snapshots on exit, and full paru/yay output. These logs can contain command
-output, file contents, and secrets printed to the terminal. Nothing leaves
-your machine, but the files persist locally.
-- Disable all logging with: `set -U __fish_config_op_logging off`
+CAUTION: **SESSION LOGGING IS OPT-IN**
+Once enabled, this configuration *can* silently record terminal output to
+`~/.terminal_history`: Kitty scrollback on window close, live tmux pane
+streams, zellij pane snapshots on exit, and full paru/yay output. These logs
+can contain command output, file contents, and secrets printed to the
+terminal. Nothing leaves your machine, but the files persist locally. Logging
+is off unless you turn it on.
+- Enable all logging with: `set -U __fish_config_op_logging on`
- Prefer a menu? Run the interactive picker: `config-settings`
+- Turn it back off with: `set -U __fish_config_op_logging off` (or erase the variable)
- See [C5 — Logging and Capture](/07-customization/#c5-logging-and-capture) for the full breakdown.
The configuration uses a structured file tree:
diff --git a/functions/__fish_config_op_enabled.fish b/functions/__fish_config_op_enabled.fish
index 80b1d76..aa68f56 100644
--- a/functions/__fish_config_op_enabled.fish
+++ b/functions/__fish_config_op_enabled.fish
@@ -15,6 +15,11 @@
# falsy master disables every unset-category component at once.
# Unset master with unset category → enabled (active by default).
#
+# One exception: __fish_config_op_logging (C5) is opt-in, because it
+# writes terminal output to disk. Unset or unrecognized means disabled,
+# and the master switch cannot enable it — only an explicit truthy
+# value turns logging on.
+#
# ARGUMENTS
# category_variable Name (without $) of the category opt-out variable:
# __fish_config_op_aliases, __fish_config_op_autoexec,
@@ -24,8 +29,8 @@
# __fish_config_op_greeting
#
# EXIT STATUS
-# 0 Component enabled (category explicitly truthy; or category unset and master not falsy)
-# 1 Component disabled (category explicitly falsy; or category unset and master falsy; or no argument with falsy master)
+# 0 Component enabled (category explicitly truthy; or category unset and master not falsy — except C5 logging, which requires an explicit truthy value)
+# 1 Component disabled (category explicitly falsy; or category unset and master falsy; or C5 logging unset; or no argument with falsy master)
#
# EXAMPLE
# if __fish_config_op_enabled __fish_config_op_aliases
@@ -43,6 +48,12 @@ function __fish_config_op_enabled --description 'Check whether an opinionated co
return 1
end
+ # C5 logging is opt-in: it writes terminal output to disk, so an unset or
+ # unrecognized value means off — the master switch cannot enable it.
+ if test "$argv[1]" = __fish_config_op_logging
+ return 1
+ end
+
# Status 3 (garbage) defers to master — an unrecognized value is not an opt-out.
__fish_variable_check __fish_config_opinionated
if test $status -eq 1