Terminal Environment: zsh, zsh-autosuggestions, fzf

Terminal Environment: zsh, zsh-autosuggestions, fzf

The companion standard to the tmux Tutorial — together they make up the full iSu terminal setup on any server. New as of 2026-07-23, first established on isutech-svr-01 (Dube TradePort); not yet applied to production-server-01 (Hetzner) or the loaned dev server as of this writing.

---

🎯 What this gives you

• zsh as the login shell, with sane history/completion defaults.
• zsh-autosuggestions — as you type, the rest of a command you’ve run before appears as greyed-out “ghost text.” Press → (right arrow) or End to accept it, or just keep typing to ignore it.
• fzf — fuzzy-finder integration for two everyday actions:
  • Ctrl+R — fuzzy search through shell history (replaces the plain, linear Ctrl+R reverse-search bash gives you by default).
  • Ctrl+T — fuzzy-find a file path and insert it at the cursor.
  • Alt+C — fuzzy-find a directory and cd into it.

None of this is exotic — it’s the same category of tooling most engineers already have locally (fish shell, oh-my-zsh, etc.), standardised here so every iSu server behaves the same way.

---

📦 Install

All three packages are in Ubuntu’s standard repositories — no manual builds or git clones needed:

sudo apt update
sudo apt install -y zsh zsh-autosuggestions fzf tmux

(tmux is included since the two setups are meant to be installed together — see the tmux Tutorial if you haven’t already.)

---

⚙️ Configuration

The canonical .zshrc lives in the all-business repo (private, working-context repo — not this DocsHub) at dube-tradeport/DOCS/infra-migration/terminal-env/.zshrc, deployed via scp per that directory’s DEPLOY.md. The relevant pieces, for reference:

# zsh-autosuggestions (apt package: zsh-autosuggestions)
if [ -f /usr/share/zsh-autosuggestions/zsh-autosuggestions.zsh ]; then
    source /usr/share/zsh-autosuggestions/zsh-autosuggestions.zsh
fi

# fzf (apt package: fzf)
if [ -f /usr/share/doc/fzf/examples/key-bindings.zsh ]; then
    source /usr/share/doc/fzf/examples/key-bindings.zsh
fi
if [ -f /usr/share/doc/fzf/examples/completion.zsh ]; then
    source /usr/share/doc/fzf/examples/completion.zsh
fi

Package paths can shift between Ubuntu versions

Confirm the actual paths before assuming these are correct on a server you’re setting up fresh:

dpkg -L zsh-autosuggestions | grep '\.zsh$'
dpkg -L fzf | grep -E 'key-bindings\.zsh|completion\.zsh'

These matched on isutech-svr-01 (Ubuntu 24.04.4 LTS) as of 2026-07-23 — worth re-checking on a different Ubuntu release before trusting them blindly.

🔀 Setting zsh as the default shell

Installing the package doesn’t change your login shell — that’s a separate step:

chsh -s "$(which zsh)"

This prompts for your account password (the same one sudo uses — not an SSH key passphrase, they’re unrelated prompts that are easy to confuse). It takes effect on your next login, not the current session — close and reopen your SSH connection to see it apply.

Verify:

getent passwd "$(whoami)"

The line should end in .../zsh.

---

✅ Verifying it’s working

After reconnecting with the new shell active:

1. Prompt check — you should see a zsh-style % prompt instead of bash’s $.
2. Autosuggestions — type the start of a command you’ve run before in this session; grey ghost-text of the rest should appear. Press → or End to accept.
3. fzf history search — press Ctrl+R; a fuzzy-search popup should appear instead of bash’s plain linear reverse-search.
4. tmux prefix — inside tmux, press Ctrl+a then r; you should see “Config reloaded” flash, confirming the paired tmux config (see the tmux Tutorial) is active too.

---

🚫 What this deliberately doesn’t include

• oh-my-zsh or any zsh framework — this is a minimal, hand-written .zshrc, not a framework. Frameworks add real startup latency and a lot of surface area for a benefit most people don’t need; add one later only if a specific gap shows up.
• A custom prompt theme (Powerlevel10k, Starship, etc.) — the shipped prompt is intentionally simple (user@host, path, git branch). Swap it if you want, but it’s not part of the standard.
• Any change to root’s shell — only applies to the working sudo user (e.g. isutech-admin), never root.

---

➡️ Rollout status

Server	Status
isutech-svr-01 (Dube TradePort)	✅ Deployed 2026-07-23
Loaned dev server (isu-tech)	✅ Deployed 2026-07-23 — merged with the existing hand-written .tmux.conf rather than overwriting it (kept its custom status bar, added the missing recommended pieces)
production-server-01 (Hetzner)	✅ Deployed 2026-07-23 to the nhla account specifically — not root. Root already has a separate, narrower .tmux.conf for Claude Code session persistence (no Ctrl+a remap) which was deliberately left untouched, not merged/overwritten.

Rollout complete across all three servers as of 2026-07-23.