Suvadu

Total recall for your terminal.

Suvadu (Tamil: "Trace" / "Footprint") replaces your shell's built-in history with a SQLite-backed store, giving you structured storage, millisecond-precision timestamps, and a modern interactive search UI — across every terminal, IDE, and AI agent you use.

Why Suvadu?

Your shell history is one of your most valuable productivity assets — but the default implementation is stuck in the 1970s. A flat text file with no structure, no search, no context, and no way to track what your AI agents are doing.

Suvadu fixes this. Every command gets a structured record with working directory, exit code, duration, executor identity, and session context. Search is fast. AI agent commands are tracked and risk-assessed automatically.

	Default Shell History	Suvadu
Storage	Flat text file	SQLite + WAL
Search	Linear scan, regex only	Fuzzy search, indexed
Context	None	Directory, exit code, duration, executor, tags
AI Agents	Invisible	Auto-detected, risk-assessed, auditable
Cross-shell	Per-shell files	Unified database
UI	Reverse-i-search	Interactive TUI with filters, preview, bookmarks

Features

High Performance

SQLite with WAL mode — low-latency writes, even with millions of records
Indexed search — fast results across your entire history
Fuzzy matching — powered by nucleo-matcher (same engine as Helix editor)

Interactive Search

Full TUI — structured table with time, session/tag, executor, path, command, status, and duration columns
Syntax highlighting — commands, flags, strings, variables, paths, and operators each get distinct colors
Smart mode — context-aware ranking boosts same-directory results (Ctrl+S)
Directory scoping — filter to current working directory (Ctrl+L or --here)
Date filters — Ctrl+F panel with "today", "yesterday", or YYYY-MM-DD ranges
Detail pane — Tab to preview full entry metadata
Deduplication — toggle unique command view with Ctrl+U

Smart Arrow Keys

Frecency ranking — Up/Down arrow prefers same-directory commands using frequency × recency scoring
Configurable via suv settings → Shell → Enable Arrow Key Navigation

AI Agent Monitoring

Auto-detection — identifies commands from Claude Code, Codex, Aider, VS Code, Cursor, Windsurf, and more
Risk assessment — every agent command classified as Critical, High, Medium, Low, or Safe
Agent dashboard — real-time TUI with timeline, risk indicators, and detail pane
Agent stats — per-agent analytics with top commands, directories, and risk breakdown
Agent report — export activity as text, markdown, or JSON
Claude Code integration — suv init claude-code captures AI-executed commands via PostToolUse hook

Tagging, Bookmarks & Notes

Session tags — categorize sessions (e.g., "work", "personal") for filtering
Auto-tagging — automatically assign tags based on working directory
Bookmarks — star favorite commands (Ctrl+B in TUI) with optional labels
Notes — annotate any entry with context (Ctrl+N in TUI)

Privacy First

Commands prefixed with a space are not recorded
Configurable regex exclusion patterns
Per-session pause (suv pause) and global disable (suv disable)
Bulk delete matching entries by pattern or date range
All data stays local — no telemetry, no external servers

More

Shell integration — Zsh (5.1+) and Bash, with Ctrl+R search and arrow key cycling
Session replay — chronological timeline with date, directory, tag, and executor filters
Stats dashboard — interactive TUI with heatmap, sparkline, hourly distribution, and top commands
Alias suggestions — analyzes history to suggest shell aliases for frequently-typed commands
Export & import — JSONL, CSV, and ~/.zsh_history import
Shell completions — Zsh, Bash, and Fish (suv completions <shell>)
Self-update — suv update with SHA256 checksum verification

Installation

Prerequisites

macOS (Apple Silicon or Intel) or Linux (x86_64 or ARM64)
Zsh 5.1+ or Bash

Homebrew (macOS — Recommended)

brew tap AppachiTech/suvadu
brew install suvadu

# Add to your shell (choose one):
echo 'eval "$(suv init zsh)"' >> ~/.zshrc && source ~/.zshrc
# or
echo 'eval "$(suv init bash)"' >> ~/.bashrc && source ~/.bashrc

Manual Install — macOS

curl -fsSL https://downloads.appachi.tech/macos/suv-macos-latest.tar.gz \
  | tar -xz \
  && sudo mv suv /usr/local/bin/ \
  && sudo ln -sf /usr/local/bin/suv /usr/local/bin/suvadu

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

Manual Install — Linux

# Auto-detects architecture (x86_64 or aarch64/Graviton)
ARCH=$(uname -m)
if [ "$ARCH" = "aarch64" ] || [ "$ARCH" = "arm64" ]; then
  URL="https://downloads.appachi.tech/linux/suv-linux-aarch64-latest.tar.gz"
else
  URL="https://downloads.appachi.tech/linux/suv-linux-latest.tar.gz"
fi

curl -fsSL "$URL" \
  | tar -xz \
  && sudo mv suv /usr/local/bin/ \
  && sudo ln -sf /usr/local/bin/suv /usr/local/bin/suvadu

# Add to your shell (choose one):
echo 'eval "$(suv init zsh)"' >> ~/.zshrc && source ~/.zshrc
# or
echo 'eval "$(suv init bash)"' >> ~/.bashrc && source ~/.bashrc

Build from Source

git clone https://github.com/AppachiTech/suvadu.git
cd suvadu
cargo build --release
sudo cp target/release/suv /usr/local/bin/

Updating

# Homebrew
brew upgrade suvadu

# Manual installations
suv update

Uninstalling

suv uninstall

Quick Start

# Verify installation
suv --help

# Check recording status
suv status

# Open interactive search (or press Ctrl+R)
suv search

# Open settings
suv settings

Usage

Interactive Search (TUI)

Ctrl+R is automatically bound to Suvadu's search when shell hooks are active.

suv search                        # Open search
suv search --query "git commit"   # Search with initial query
suv search --unique               # Unique commands only
suv search --here                 # Commands from current directory
suv search --executor agent       # Filter by executor type

Keyboard Shortcuts

Key	Action
Type	Fuzzy search across history
`Up` / `Down`	Navigate results
`Tab`	Toggle detail preview pane
`Enter`	Select and execute command
`Esc`	Exit without selecting
`Ctrl+S`	Toggle Smart mode (context-aware ranking)
`Ctrl+L`	Toggle directory-scoped filter
`Ctrl+U`	Toggle unique/deduplicated view
`Ctrl+F`	Open filter panel (date, tag, exit code, executor)
`Ctrl+B`	Toggle bookmark on selected entry
`Ctrl+N`	Add or edit note on selected entry
`Ctrl+T`	Associate current session with a tag
`Ctrl+Y`	Copy selected command to clipboard
`Ctrl+D`	Delete selected entry (with confirmation)
`Ctrl+G`	Go to specific page
`Left` / `Right`	Previous / next page

Smart Fallback: If Suvadu is disabled or paused, Ctrl+R automatically reverts to your shell's default history search.

Session Replay

suv replay                              # Current session
suv replay --after today                # Today's commands
suv replay --after yesterday --here     # Yesterday, this directory
suv replay --session <id>               # Specific session

Stats Dashboard

suv stats                # Interactive TUI dashboard
suv stats --days 30      # Last 30 days
suv stats --text         # Plain text output

Agent Monitoring

Monitor and audit every command your AI agents run.

# Interactive dashboard with timeline and risk indicators
suv agent dashboard
suv agent dashboard --executor claude-code
suv agent dashboard --after yesterday --here

# Per-agent analytics — breakdown cards, top commands, risk table
suv agent stats
suv agent stats --days 7

# Export agent activity report
suv agent report
suv agent report --format markdown > report.md
suv agent report --format json | jq .

Dashboard Controls

Key	Action
`Up` / `Down`	Navigate timeline
`Tab`	Toggle detail pane
`1` / `2` / `3` / `4`	Period: 7d / 30d / 90d / All
`a`	Cycle agent filter
`r`	Toggle risk-only filter (medium+ risk)
`Ctrl+Y`	Copy selected command to clipboard
`q` / `Esc`	Quit

Risk Levels

Every agent command is automatically classified:

Level	Examples	Indicator
Critical	`rm -rf /`, `DROP TABLE`, `git push --force origin main`	`!!`
High	`chmod 777`, `npm install`, `pip install`, config overwrites	`!!`
Medium	`git reset`, `docker run`, environment modifications	`~`
Low	File writes, branch operations	`.`
Safe	`git status`, `ls`, `cargo test`, `grep`	`ok`

Alias Suggestions

suv suggest-aliases                    # Interactive TUI
suv suggest-aliases --text             # Plain text output
suv suggest-aliases --days 30 -c 5     # Last 30 days, min 5 uses

Executor Tracking

Suvadu automatically detects and records who or what executed each command:

Type	Executors	Detection
Human	Terminal	Interactive TTY check
AI Agent	Claude Code, Codex, Aider, Continue	Environment variables
IDE	VS Code, Cursor, Windsurf, Antigravity, IntelliJ, PyCharm	Environment variables
Bot	Copilot	Environment variables
CI/CD	GitHub Actions, GitLab CI, CircleCI	Environment variables
Programmatic	Subprocess	Non-interactive shell fallback

Filter by executor in the search TUI (Ctrl+F → Executor) or via CLI:

suv search --executor agent
suv search --executor cursor

`suv wrap` — Agent & Script Integration

For agents and scripts that don't load shell hooks:

suv wrap -- git status
suv wrap --executor-type agent --executor claude-code -- npm test
suv wrap --executor-type ci --executor github-actions -- make deploy

Managing Recording

suv disable              # Stop recording globally
suv enable               # Resume recording
eval $(suv pause)        # Pause current session only
suv status               # Check recording state

Tags, Bookmarks & Notes

# Tags
suv tag create "work" --description "Work related"
suv tag list
suv tag update "work" --new-name "office" --description "Office stuff"
suv tag associate "work"

# Bookmarks
suv bookmark add "docker compose up -d"
suv bookmark list
suv bookmark remove "docker compose up -d"

# Notes
suv note <id> -c "remember: this fixed the build"
suv note <id>              # View
suv note <id> --delete     # Remove

Bulk Deletion

suv delete "rm -rf" --dry-run              # Preview before deleting
suv delete "rm -rf"                        # Delete by substring
suv delete "^git (commit|status)" --regex  # Delete by regex
suv delete "" --before 2024-01-01          # Delete entries before a date

Export & Import

# Export
suv export > history.jsonl
suv export --format csv > history.csv
suv export --after 2025-01-01 --before 2025-06-01 > q1-q2.jsonl

# Import
suv import history.jsonl
suv import history.jsonl --dry-run
suv import --from zsh-history ~/.zsh_history

Privacy

Prefix a command with a space to prevent recording:

 secret_command_here   # NOT saved to history

Configure exclusion patterns in suv settings → Exclusions, or in config.toml:

exclusions = ["^ls$", "^pwd$", "password"]

Configuration

Config file location:

macOS: ~/Library/Application Support/suvadu/config.toml
Linux: ~/.config/suvadu/config.toml

Interactive Settings

suv settings

Opens a TUI with tabs for Search, Shell, Exclusions, and Auto Tags.

Reference

# Master switch
enabled = true

[search]
page_limit = 50                      # Rows per page (10-5000)
show_unique_by_default = false        # Start in deduplicated mode
filter_by_current_session_tag = false # Scope search to current tag
context_boost = true                  # Boost same-directory results (Smart mode)
show_detail_pane = true               # Show detail pane on search open

[shell]
enable_arrow_navigation = true        # Up/Down arrows cycle history

[auto_tags]
"/Users/alice/work" = "work"
"/Users/alice/personal" = "personal"

# Regex exclusion patterns (invalid regex falls back to substring match)
exclusions = ["^ls$", "^pwd$", "^cd$"]

Exclusion Patterns

Pattern	Effect
`^ls$`	Ignores exactly `ls`, still records `ls -la`
`password`	Ignores any command containing "password"
`^git .*`	Ignores all git commands

IDE & AI Agent Integrations

Claude Code

suv init claude-code

Installs a PostToolUse hook and configures ~/.claude/settings.json. Restart Claude Code after setup.

Cursor

suv init cursor

Auto-detects Cursor via $CURSOR_INJECTION and $CURSOR_TRACE_ID environment variables. No additional configuration needed.

Antigravity

suv init antigravity

Auto-detects Antigravity via the $ANTIGRAVITY_AGENT environment variable. No additional configuration needed.

Verify any integration:

suv search --executor agent       # Claude Code
suv search --executor cursor      # Cursor
suv search --executor antigravity # Antigravity

How It Works

┌──────────────────────────┐
│     Zsh / Bash Shell     │
│  preexec → start time    │
│  precmd  → exit code,    │
│            duration       │
│  suv add → record entry  │
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│    SQLite + WAL Mode     │
│    suvadu/history.db     │
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│    suv search (TUI)      │
│    Ctrl+R binding        │
│    Indexed queries       │
│    Fast response          │
└──────────────────────────┘

Shell hooks use native $EPOCHREALTIME (Zsh 5.1+ / Bash 5+) for millisecond-precision timestamps with zero external dependencies.

Database location:

macOS: ~/Library/Application Support/suvadu/history.db
Linux: ~/.local/share/suvadu/history.db

Schema

Table	Key Columns
`sessions`	`id` (UUID), `hostname`, `created_at`, `tag_id`
`entries`	`command`, `cwd`, `exit_code`, `duration_ms`, `started_at`, `ended_at`, `executor_type`, `executor`, `tag_id`, `context`
`tags`	`name`, `description`

Command Reference

Command	Description
Search & Browse
`suv search`	Interactive search TUI
`suv search --query "git"`	Search with initial query
`suv search --executor agent`	Filter by executor type
`suv search --unique`	Deduplicated results
`suv search --here`	Commands from current directory
`suv replay`	Replay current session as timeline
`suv replay --after today --here`	Today's commands in this directory
Stats & Analytics
`suv stats`	Interactive stats dashboard
`suv stats --days 30`	Stats for the last 30 days
`suv stats --text`	Plain text output
Agent Monitoring
`suv agent dashboard`	Interactive agent monitoring TUI
`suv agent dashboard --executor claude-code`	Filter to one agent
`suv agent stats`	Per-agent analytics and risk breakdown
`suv agent report`	Export agent activity report (text)
`suv agent report --format markdown`	Export as markdown
`suv agent report --format json`	Export as structured JSON
Organization
`suv tag create <name>`	Create a tag
`suv tag list`	List all tags
`suv tag associate <name>`	Tag current session
`suv bookmark add <cmd>`	Bookmark a command
`suv bookmark list`	List all bookmarks
`suv note <id> -c "note"`	Add a note to an entry
`suv suggest-aliases`	Suggest shell aliases (interactive TUI)
Recording Control
`suv status`	Show recording status
`suv enable` / `suv disable`	Toggle recording
`suv pause`	Pause current session
`suv settings`	Interactive settings TUI
Data
`suv delete <pattern>`	Delete matching entries
`suv export`	Export history as JSONL
`suv export --format csv`	Export as CSV
`suv import <file>`	Import from JSONL file
`suv import --from zsh-history`	Import from `~/.zsh_history`
Integration
`suv wrap -- <cmd>`	Record a command from agents/scripts
`suv init zsh` / `suv init bash`	Generate shell hooks
`suv init claude-code`	Set up Claude Code capture
`suv init cursor`	Set up Cursor tracking
`suv init antigravity`	Set up Antigravity tracking
Utilities
`suv completions <shell>`	Generate shell completions (zsh, bash, fish)
`suv man`	Generate man page
`suv update`	Update to latest version
`suv uninstall`	Remove Suvadu

Development

git clone https://github.com/AppachiTech/suvadu.git
cd suvadu

make dev      # Run the app
make test     # Run tests
make lint     # Run clippy + format check
make help     # Show all available commands

cargo test                # Run all tests
cargo fmt -- --check      # Check formatting
cargo clippy -- -D warnings  # Lint
cargo build --release     # Release build

Release

make release-patch  # 0.1.0 → 0.1.1
make release-minor  # 0.1.x → 0.2.0
make release-major  # 0.x.x → 1.0.0

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for development setup, project structure, and guidelines.

Security

For security-related matters including vulnerability reporting, data storage design, and privacy features, see SECURITY.md.

License

MIT — Appachi Tech

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.github		.github
scripts		scripts
src		src
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
build.rs		build.rs
rustfmt.toml		rustfmt.toml

License

AppachiTech/suvadu

Folders and files

Latest commit

History

Repository files navigation

Suvadu

Table of Contents

Why Suvadu?

Features

High Performance

Interactive Search

Smart Arrow Keys

AI Agent Monitoring

Tagging, Bookmarks & Notes

Privacy First

More

Installation

Prerequisites

Homebrew (macOS — Recommended)

Manual Install — macOS

Manual Install — Linux

Build from Source

Updating

Uninstalling

Quick Start

Usage

Interactive Search (TUI)

Keyboard Shortcuts

Session Replay

Stats Dashboard

Agent Monitoring

Dashboard Controls

Risk Levels

Alias Suggestions

Executor Tracking

suv wrap — Agent & Script Integration

Managing Recording

Tags, Bookmarks & Notes

Bulk Deletion

Export & Import

Privacy

Configuration

Interactive Settings

Reference

Exclusion Patterns

IDE & AI Agent Integrations

Claude Code

Cursor

Antigravity

How It Works

Schema

Command Reference

Development

Release

Contributing

Security

License

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Languages

`suv wrap` — Agent & Script Integration

Packages