Settings

Configure Suvadu through an interactive terminal UI and TOML files — themes, 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.

Search

Configure search behavior:

• Page limit — number of results per page (default: 50)
• Show unique by default — start search in deduplicated mode
• Context boost (Smart mode) — for typed queries, boost results recorded in exactly the current directory (see Smart Mode)
• 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.

Or set directly in config.toml:

[search]
page_limit = 50
context_boost = true
recall_show_agents = false
show_detail_pane = true
vim_mode = false
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.

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. See the MCP reference for the config format.

In 0.4.1 the MCP tab lists 15 of the server's 21 default tools and 7 of its 8 resources. The session tools (list_agent_sessions, get_agent_session, resolve_current_agent_session), the skills tools (list_skills, get_skill, search_skills), and the suvadu://skills/index resource are not shown there; to disable one of them, add its name to disabled_tools (or its URI suffix to disabled_resources) in config.toml.

The two optional write tools are also not available in suv settings in 0.4.1. 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"]

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. Scalars and arrays replace the corresponding global value completely; an exclusions list does not append to the global list.

• Command recording loads the overlay using the recorded command's working directory, including recording, exclusion, and redaction settings.
• OpenCode's live prompt cache (paired with the commands run for it) loads the overlay using the session's own directory, so redaction and the prompt-length cap follow project config there too. Claude Code's and Codex's prompt caches still use only global config.
• 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'. Invalid project configuration can make CLI startup fall back to defaults, while recording reports a config error.

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. Saving rewrites the whole file from the current settings, so comments you added by hand are not kept. 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.