Shell Integration

Shell integration connects Suvadu to your terminal so that every command you run is automatically recorded with full metadata: working directory, duration, exit code, and executor.

Zsh Setup

Add the Suvadu hook to your ~/.zshrc and reload:

echo 'eval "$(suv init zsh)"' >> ~/.zshrc && source ~/.zshrc

This appends a single line to your Zsh configuration. The suv init zsh command outputs the shell functions that Suvadu needs; eval loads them into your current session.

Bash Setup

Add the Suvadu hook to your ~/.bashrc and reload:

echo 'eval "$(suv init bash)"' >> ~/.bashrc && source ~/.bashrc

For login shells that only source ~/.bash_profile, add the same line to ~/.bash_profile instead, or make sure your ~/.bash_profile sources ~/.bashrc.

What the Hooks Do

The shell hooks set up two functions that run transparently around every command you execute:

• Pre-exec hook: Fires just before a command starts. It captures the command text, working directory, timestamp, and which executor is running the command (you, or an AI agent like Claude Code or Cursor).
• Post-exec hook: Fires after the command finishes. It records the exit code and how long the command took (duration in milliseconds).

Both hooks are lightweight and add sub-millisecond overhead. They do not modify your command, its output, or its exit code.

Verify Shell Integration

After setting up the hooks, run:

suv status

You should see output similar to:

Suvadu v0.4.0
Database: ~/.local/share/suvadu/history.db
Recording: enabled
Shell: zsh
Session: a1b2c3d4

Key things to check:

• Recording: enabled — confirms that commands are being captured
• Shell: zsh (or bash) — confirms which shell was detected
• Session — a unique ID for your current terminal session

Try running a few commands, then verify they were recorded:

suv search

Your recent commands should appear in the search TUI.

Terminal Multiplexers

Suvadu works with tmux, screen, Zellij, and any other terminal multiplexer. Each pane or window gets its own unique session ID, so commands are tracked separately per pane. No extra configuration is needed.

Pausing and Disabling Recording

Sometimes you want to stop recording temporarily — for example, when entering sensitive commands.

Pause (Current Session Only)

Pause recording for just the current shell session. Other terminal windows and panes continue recording normally:

suv pause

Recording resumes automatically when you open a new terminal session, or you can re-source your shell config:

source ~/.zshrc    # Zsh
source ~/.bashrc   # Bash

Disable / Enable (Global)

Globally disable recording across all sessions:

suv disable

To re-enable recording globally:

suv enable

When disabled, suv status will show "Recording: disabled". No commands are captured in any terminal until you run suv enable.

Fish Shell

Fish shell is not yet supported. It is on the Suvadu roadmap. If you use Fish, you can track progress on GitHub Issues.

Troubleshooting

• "command not found: suv" — The suv binary is not in your PATH. Check your installation and make sure /usr/local/bin or ~/.cargo/bin is in your PATH.
• "no such file or directory" pointing at an old path (e.g. suv:8: no such file or directory: /opt/homebrew/bin/suv) — The shell hook records the absolute path of the suv binary when your session starts. If you later move the binary — switching package managers (for example Homebrew → Cargo), running brew unlink suvadu, or uninstalling and reinstalling elsewhere — already-open shells keep pointing at the old, now-deleted path and print this error on every prompt. Reload the shell to pick up the new location: exec zsh (or exec bash), or just open a new terminal.
• Recording shows "disabled" after setup — You may have previously run suv disable. Run suv enable to re-enable recording globally.
• Commands not appearing in search — Make sure you sourced your shell config after adding the eval line. Open a new terminal tab and try again. Run suv status to confirm hooks are active.
• Duplicate eval lines — If you ran the setup command more than once, you may have multiple eval "$(suv init zsh)" lines in your config. This is harmless but you can remove duplicates. Only one line is needed.