I built a local-only shell history manager in Rust with AI agent tracking

#rust #terminal #cli #opensource

Every shell history tool I tried either wanted me to create a cloud account or had no way to track what my AI agents were running.

So I built Suvadu — a local-only, SQLite-backed shell history manager with a TUI, agent monitoring, and automatic secrets redaction. No cloud, no account, no data leaving your machine.

The name is Tamil for "trace" or "footprint."

Why I built something different

Atuin is a great tool — and yes, you can run it in local-only mode. But Atuin is designed around sync. The account system, the server component, the encryption layer — that's where the engineering focus is, and that's what makes it powerful for teams and multi-machine setups.

I wanted something different: a tool that's local-first by design, not local as an opt-out. No server component in the codebase, no account system, no sync protocol — just a SQLite database and a TUI. Fewer moving parts, smaller attack surface, simpler mental model.

The other thing I couldn't find in any existing tool was AI agent monitoring. With Claude Code, Cursor, and Aider running commands autonomously, I wanted to know exactly what they were executing and flag risky operations (rm -rf, git push --force, permission changes) before they cause damage.

So Suvadu is built around two ideas: local-only by architecture and AI agents as first-class citizens in your history.

Feature	Suvadu	Atuin	McFly	Hstr
Storage	Local SQLite	Cloud or local	Local SQLite	In-memory
Cloud sync	No (local-only by design)	Yes (local mode available)	No	No
TUI	Full-screen + detail pane	Full-screen	Inline overlay	Full-screen
AI agent tracking	Auto-detect + risk assess	No	No	No
Secrets redaction	Auto before storage	No	No	No
Activity heatmap	Yes (5-tier)	Dashboard (cloud)	No	No
Themes	3 built-in, hot-swap	No	No	No

Search

Fuzzy search powered by nucleo (same engine as Helix editor). Features:

Toggleable detail pane showing full metadata for each entry
Smart mode — context-aware ranking that boosts same-directory commands
Directory scoping, date filters, tag filters, executor filters
Unique-command deduplication toggle
Bookmarks and notes on any entry
Responsive layout that adapts to terminal width

Stats

A GitHub-style activity heatmap with 5 intensity tiers. Cycle through time periods (30d / 90d / 180d / 365d) with a single keypress. Includes an executor breakdown showing which tools ran what.

Agent monitoring

This is the feature I use the most. Every command run by an AI agent gets automatically detected and risk-assessed:

Critical: rm -rf /, git push --force origin main
High: chmod 777, npm install, config overwrites
Medium: git reset, docker run
Safe: git status, ls, cargo test

There's an interactive dashboard with a timeline, per-agent analytics, and exportable reports (text, markdown, JSON). You can filter by agent, risk level, or time period.

Setting it up for Claude Code is one command:

suv init claude-code

Privacy and security

Commands prefixed with a space are never recorded
Configurable regex exclusion patterns
API keys, tokens, and passwords are auto-redacted before they hit the database
Database and config files use owner-only permissions (0o600)
Self-update verifies binary signatures via Minisign
All data stays local — no telemetry, no external servers, ever

Other bits

Session timeline — browse history by terminal session with an interactive TUI
Alias suggestions — analyzes your history and suggests shell aliases for frequently-typed commands
Export/import — JSONL, CSV, JSON, and ~/.zsh_history import
Shell completions — Zsh, Bash, and Fish

The stack

Rust with ratatui for the TUI
SQLite (via rusqlite) with WAL mode for storage
nucleo-matcher for fuzzy search
Minisign for release signature verification
Zsh and Bash hooks for transparent recording

Install

# macOS (Homebrew)
brew tap AppachiTech/suvadu && brew install suvadu

# macOS / Linux (direct download)
curl -fsSL https://downloads.appachi.tech/install.sh | bash

# From source
cargo install suvadu