---
title: Fish Shell Configuration
description: Reference manual for the rootiest fish configuration.
manTitle: DESCRIPTION
sidebar:
  order: 3
helpKeywords:
- description
- autopair
- puffer
- puffer-fish
- logging-events
---

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)
- Automatic Python virtualenv activation on directory change
- Cross-platform package management via pkg and fish-deps
- AI session 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`
> - Prefer a menu? Run the interactive picker: `config-settings`
> - See Section 7 (C5 - Logging and Capture) for the full breakdown.

The configuration is split across:

    ~/.config/fish/
    ├── config.fish               Main entry point; sets env vars and PATH
    ├── conf.d/
    │   ├── abbr.fish               All abbreviations
    │   ├── autopair.fish           Auto-pair brackets and quotes (bundled from jorgebucaran/autopair.fish)
    │   ├── cheat.fish              cheat.sh tab completions
    │   ├── done.fish               Desktop notifications for long commands
    │   ├── first_run.fish          One-time init: Fisher bootstrap, theme, welcome
    │   ├── key_bindings.fish       Custom key bindings and Vi mode
    │   ├── logging-events.fish     C5 --on-variable event handlers; syncs logging state at startup
    │   ├── kitty-watcher-reminder.fish  C5 per-session reminder to set up the Kitty watcher
    │   ├── paru-wrapper.fish       Auto-generates ~/.local/bin/paru logging wrapper
    │   ├── puffer.fish             !! / !$ / ./ expansion (bundled from nickeb96/puffer-fish)
    │   ├── tmux-logging.fish       C5 starts tmux pipe-pane capture when fish runs inside tmux
    │   ├── zellij-logging.fish     C5 fish_exit handler dumping zellij pane scrollback on exit
    │   ├── sponge_privacy.fish     Sponge privacy patterns; filters credentials from history
    │   ├── starship.fish           fish_prompt with OSC 133 shell-integration markers
    │   ├── tailscale.fish          Tailscale CLI tab completions
    │   ├── theme.fish              Catppuccin syntax highlight colors
    │   ├── tricks.fish             PATH, bang-bang helpers, bat man pages, aliases
    │   ├── wakatime.fish           WakaTime shell hook
    │   ├── yay-wrapper.fish        Auto-generates ~/.local/bin/yay logging wrapper
    │   └── zoxide.fish             Zoxide z/zi integration; overrides cd
    ├── functions/                Custom functions, one per file, autoloaded
    ├── completions/              Tab completion scripts
    ├── integrations/
    │   └── fzf.fish                FZF Catppuccin theme and key binding config
    ├── scripts/
    │   ├── clean_progress_log.py   Strips paru/yay typescript animations to clean static logs
    │   └── agents-tools/           AGENTS.md version-bump script and git hooks (wired via core.hooksPath)
    └── docs/                     Offline documentation and compiled man page
        ├── fish-config.md          Primary source manual (terminal-readable)
        ├── fish-config.1           Compiled man page (auto-generated by CI)
        ├── fish-config.index       Section index for help config navigation
        ├── html/                   Chunked HTML docs (auto-generated by CI)
        └── wiki/                   Markdown wiki (auto-generated by CI)

---