Settings

Configure Suvadu through an interactive terminal UI and TOML files — themes, search ranking, what is captured, exclusion patterns, auto-tags, and agent detection rules.

Quick Start

Launch the interactive settings TUI to browse and modify common configuration options.

suv settings

The TUI presents a tabbed interface where you can navigate between sections using arrow keys, edit values inline, and save changes on exit.

Settings Sections

Theme

Choose the visual theme for Suvadu's TUI components (search, stats, replay, settings). Themes control colors, borders, and highlight styles across all interactive views.

Home

Two rows in the Shell tab set up Suvadu Home:

• Startup Screen (home.startup) — what a bare suv opens at a terminal: home, the Home screen, or help, the command overview. It reads home (default) until you choose, and nothing is written for it until then. suv home opens Home whatever it says, and scripts, pipes and TERM=dumb always get the overview.
• Home Icons (home.icons) — ascii (the default) shows the category names alone, for every terminal and font; unicode adds a monochrome symbol before each. The labels are the same either way.

Both are read from your own config only: a project's .suvadu.toml cannot set them, and a [home] section in one is ignored.

[home]
startup = "help"   # or "home", the default
icons = "ascii"    # or "unicode"

Update checks

Check for Updates (update.check), also in the Shell tab, lets Suvadu look up the newest release number once a day and mention a newer one before a command you run at a terminal. It is on by default; see Update Notices. Like the Home rows, only your own config sets it, and SUVADU_NO_UPDATE_CHECK=1 turns it off for one shell.

[update]
check = false

Capture

Since 0.5.1 three more rows in the Shell tab decide what is recorded beside each command. A project's .suvadu.toml can turn each of them off but not on.

• Record Git Branch (shell.capture_git_branch, on by default) — keep the git branch each command started on, read from the repository's own files with no git process. See Git Branch Capture.
• Keep Failure Output (capture.failure_output, off by default) — keep the last 4 KB a failed command printed, from agent hooks and suv wrap only; commands typed in your shell never have it. See Failure Output.
• Record Agent Git Snapshots (agent.record_git_snapshots, on by default) — take a git snapshot (commit, branch and changed paths, never contents) at an agent session's first prompt and each turn end. See Agent Git Snapshots.

[shell]
capture_git_branch = true

[capture]
failure_output = false

[agent]
record_git_snapshots = true

Search

Configure search behavior:

• Page limit — number of results per page (default: 50; up to 10,000, the same limit the config file accepts, since 0.5.1)
• Start in Commands View (search.show_unique_by_default) — open recall with identical commands grouped into one row, with when each last ran and how often; turn it off to start with every run (Executions). Ctrl+U switches views either way. On by default since 0.5.0 for a config that does not set it; a value already in your config.toml is kept.
• Context boost (Smart mode) — for typed queries, rank by Smart mode: results recorded in exactly the current directory, and since 0.5.1 by frecency, by outcome and by what you usually run next (see Smart Mode)
• Sequence Boost (Smart Mode) (search.sequence_boost, on by default, since 0.5.1) — the part of Smart mode that boosts what you usually run after this shell's last command. Turn it off to keep the rest of Smart mode without it.
• Show detail pane — open the detail preview pane on search launch
• Show AI-agent commands in recall — when off (the default), Up-arrow recall and Ctrl+R show only your own commands; toggle with Ctrl+A in search or Alt+A during arrow-key recall
• Vim mode — enable vim-style modal navigation (j/k, Ctrl+U/Ctrl+D, / to search, q to quit). See Search → Vim Bindings for details.
• Default match mode (search.match_mode) — how every recall reads a query: terms (the default), literal, prefix or fuzzy. Ctrl+X still cycles it live, and --match overrides it for one run. See Matching Modes and Scopes.
• Starting scope (search.scope) — where recall opens: all (the default), directory, workspace or session. Ctrl+P cycles it live, Ctrl+R resets it, and --scope overrides it for one run.
• Compact recall (search.compact) — draw recall inline under the prompt instead of full screen, as --compact does for one run. Off by default.

Since 0.5.0 the last three are on the Search tab; before that they needed a hand edit of config.toml. Enter or Space cycles or toggles each one. Saving writes the same words --match and --scope accept and keeps every other key in the file, including ones this build does not know. All three default to the behaviour of earlier releases.

Or set directly in config.toml:

[search]
page_limit = 50
show_unique_by_default = true   # false: start in Executions (every run)
context_boost = true
recall_show_agents = false
show_detail_pane = true
vim_mode = false
match_mode = "terms"      # or literal, prefix, fuzzy
scope = "all"             # or directory, workspace, session
compact = false
sequence_boost = true
length_threshold = 80
human_boost_percent = 33
cwd_boost_percent = 50

Search Scoring

Tune how typed-query results are ranked within the same match tier. These settings adjust the matcher score applied during search (see How results are ranked):

• Length threshold (10–500, default 80) — Commands longer than this many characters have their score scaled by √(threshold ÷ length). Shorter commands rank higher for the same match quality.
• Human boost % (0–100, default 33) — Percentage boost for commands from a human terminal (or with an unknown executor) over agent, IDE, CI, and script commands. Set to 0 to treat them equally.
• CWD boost % (0–100, default 50) — Percentage boost for commands recorded in exactly the current directory (not its subdirectories) when Smart Mode (Ctrl+S) is enabled. Set to 0 to disable directory-based ranking.

Exclusion Patterns

Define regex patterns for commands that should not be recorded. Any command matching an exclusion pattern is silently dropped before it reaches the database. Common patterns include:

• ^ls$ — skip bare ls calls
• ^cd — skip directory changes
• ^pwd$ — skip pwd
• ^clear$ — skip terminal clears
• ^exit$ — skip exit commands

Patterns use standard Rust regex syntax. Add as many as you need to keep your history clean and focused. Since 0.5.1 the settings screen refuses a blank pattern, which would stop every command containing a space from being recorded.

Auto-tags

Map directories to tags so that every session started in (or below) a directory is automatically tagged. For example:

• ~/work → Work
• ~/projects/api → API
• ~/dotfiles → Dotfiles

Auto-tags eliminate manual tagging. Combined with suv stats --tag and suv search --tag, they give you per-project analytics and search filtering automatically.

Agent Detection Rules

Configure how Suvadu identifies AI agent and IDE executor origins. Each rule consists of:

• Name — a human-readable label (e.g., "Claude Code", "Cursor", "Aider").
• Environment variable — the env var Suvadu checks to detect this agent (e.g., CLAUDE_CODE, CURSOR_SESSION_ID).
• Executor type — one of agent, ide, or ci.

Several agents are pre-configured out of the box. Use this section to add detection rules for any custom or new AI tools you use.

Agent

Settings for AI-agent capture and risk assessment:

• Show risk in search — show the risk badge for agent commands in the search detail pane.
• Prompt capture length (prompt_capture_max_chars, default 4000, range 1–100000) — how much of an agent's prompt is captured per command.
• Risk ignore patterns (risk_ignore_patterns) — regexes for commands you want excluded from risk findings (suppress false positives).

[agent]
show_risk_in_search = true
prompt_capture_max_chars = 4000
risk_ignore_patterns = ["^my-safe-tool "]

Custom Risk Patterns

Add rules in config.toml to flag commands specific to your workflow. Each rule contains a Rust regex, a level (low, medium, high, or critical), and an optional description:

[[agent.risk_extra_patterns]]
pattern = '^internal-deploy\s+production\b'
level = "critical"
description = "Production deployment needs review"

The highest matching risk wins. Ignore patterns suppress findings; invalid custom regexes or levels are skipped with a warning. See Risk Assessment and Command Guard.

MCP, Saved Summaries, and Skills Proposals

The MCP tab controls tools, resources, query defaults, and excluded directories — every MCP tool and resource enforces the exclusion list, so those directories' commands never reach a connected agent. Ctrl+A on the tab always adds a directory. See the MCP reference for the config format.

Since 0.4.2 the MCP tab lists every tool and resource the server can serve, including the session tools, the skills tools, and the suvadu://skills/index resource. The tab and the server are driven by one shared catalog, so what you toggle here is exactly what a connected agent sees. In 0.4.1 the tab showed only 15 of the then 21 default tools and 7 of the 8 resources, and the rest had to be disabled by hand in config.toml.

The two optional write tools are in the same tab since 0.4.2; in 0.4.1 they were config-file only. Both are off by default. To let a connected agent save session summaries you asked for, or submit skills for review, add these keys to the [mcp] section of the global config file (see Config File Locations). If the file already has an [mcp] header, add them under it rather than creating a second one — invalid TOML makes the MCP server start with default settings, with both write tools off.

[mcp]
allow_session_summaries = true   # adds the save_session_summary tool
allow_skill_proposals = true     # adds the propose_skill tool

Set only the one you want. The MCP server reads configuration once when it starts, so restart your AI client (or its MCP server) afterwards; the new tool appears the next time the client lists tools. A name in disabled_tools still hides the tool. Skill proposals become active only after approval in suv skills (Ctrl+P). See the full MCP reference.

Redaction

Secret redaction runs before commands are stored. In addition to the built-in patterns, supply your own:

• Enabled (default true) — turn secret redaction on or off.
• Extra patterns (extra_patterns) — your own regexes; any match is replaced with the redaction placeholder. Useful for internal/corporate secret formats the built-ins don't cover.

[redaction]
enabled = true
extra_patterns = ["CORP-[A-Z0-9]8"]

Redaction runs when a command is recorded, so a pattern you add here does not reach history you already have. Run suv redact to apply the current rules, yours included, to what is already stored; it runs even with enabled = false.

See SECURITY.md for what redaction does and does not cover.

Config File Locations

Suvadu stores its configuration in a TOML file. You can edit it directly; the TUI is the easiest way to change the options it exposes. On Linux, $XDG_CONFIG_HOME and $XDG_DATA_HOME replace ~/.config and ~/.local/share when set.

Per-Project Configuration

Version 0.4.0 can merge a .suvadu.toml file over global configuration. It searches from the relevant directory upward to the filesystem root and uses only the nearest file; it does not merge every ancestor or stop at a Git boundary.

# .suvadu.toml in the project directory
exclusions = ['^internal-secret-tool\b']

[[agent.risk_extra_patterns]]
pattern = '^internal-deploy\s+production\b'
level = "critical"
description = "Review production deployments in this project"

Tables merge key by key. Since 0.5.1 a project overlay can only tighten privacy: it cannot turn redaction off or recording back on, its exclusions and redaction.extra_patterns are added to your global lists instead of replacing them, and the capture switches (capture_git_branch, failure_output, record_git_snapshots) can be turned off there but not on. Other scalars and arrays still replace the global value.

• Command recording loads the overlay using the recorded command's working directory, including recording, exclusion, and redaction settings.
• The agent prompt caches (each prompt paired with the commands run for it) load the overlay using the prompt's own directory, so redaction and the prompt-length cap follow project config there too: OpenCode's since 0.4.1, Claude Code's and Codex's since 0.5.1, and Cursor's with its workspace's policy.
• CLI risk rules and theme load the overlay from the directory where you invoke Suvadu.
• Search options, the settings editor, and MCP still use only global config. The settings TUI edits the global file; it does not edit project overlays.

Use valid TOML and check custom rules with suv guard --verbose 'your command'. Since 0.5.1 a file that does not load never stops capture or turns the policy off: if a .suvadu.toml does not load, recording, transcript imports and the prompt caches use the global config; if config.toml itself does not load, the built-in defaults, with redaction on. The failure is noted in last-capture-error in the data directory, and suv doctor names the broken file.

Database Locations

Your shell history is stored in a local SQLite database in WAL mode. Suvadu does not sync or upload it; a connected MCP client receives only the data it requests, and may send that to its model provider under its own settings. Backups created by suv backup and before destructive deletes go in a backups folder in the same directory. See Privacy for everything that is stored.

Recording Control

Suvadu provides three commands to control whether commands are recorded to the database.

Enable recording

Turn recording on. This is the default state after installation.

suv enable

Disable recording

Turn recording off permanently until you re-enable it. No commands will be captured while disabled.

suv disable

Pause recording

Temporarily pause recording for the current shell session only. Recording resumes automatically when you open a new terminal. Useful when you need to run sensitive commands without logging them.

suv pause

How It Works

The suv settings TUI reads from and writes to the TOML config file. Since 0.5.1 saving keeps your comments and any keys it does not recognise, and auto-tags and custom agents deleted there stay deleted. Ctrl+C leaves without saving. New CLI invocations load saved changes; the MCP server reads configuration only at startup, so restart your AI client (or its MCP server) after changes. The config file is human-readable and can be version-controlled or copied between machines. If the config file is missing, Suvadu uses built-in defaults; the file is written when you save from suv settings or run suv enable/suv disable.