julianobarbosa/claude-code-skills/atuin

Name: atuin
Author: julianobarbosa

Claude Code and agent skill by julianobarbosa/claude-code-skills

Trust tier 2

community

LLM review pending

Source check pending

Checking that the SKILL.md file is still in the repository.

Shell history management with Atuin. Use when configuring shell history, setting up history sync, searching command history, importing history from other shells, troubleshooting atuin issues, or optimizing history workflows. Covers installation, sync setup, search modes, statistics, and self-hosting.

Install

npx vskill@latest install julianobarbosa/claude-code-skills/atuin

SKILL.md

Atuin Skill

Magical shell history with encrypted sync across all your machines.

Overview

Atuin replaces your shell history with a SQLite database and provides:

Full-screen history search UI (Ctrl+R / Up arrow)
End-to-end encrypted sync across machines
Context logging (exit code, cwd, hostname, duration)
Statistics and analytics
Filter modes (session, directory, global)
Quick navigation with Alt+number keys

Supported Shells

Shell	Support Level
Zsh	Full
Bash	Full
Fish	Full
Nushell	Full
Xonsh	Full

Quick Start

Installation

bash

# Official installer (recommended)
curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh | sh
 
# macOS (Homebrew)
brew install atuin
 
# Cargo
cargo install atuin
 
# Arch Linux
pacman -S atuin

Shell Integration

Zsh (~/.zshrc):

zsh

eval "$(atuin init zsh)"

Bash (~/.bashrc):

bash

eval "$(atuin init bash)"

Fish (~/.config/fish/config.fish):

fish

atuin init fish | source

Nushell (config.nu):

source ~/.local/share/atuin/init.nu

First-Time Setup

bash

# Import existing history
atuin import auto
 
# Optional: Register for sync
atuin register -u <USERNAME> -e <EMAIL>
 
# Verify setup
atuin doctor

Search Modes

Interactive Search (Ctrl+R)

Key	Action
`Ctrl+R`	Open search UI
`Up/Down`	Navigate history
`Tab`	Select without executing
`Enter`	Execute command
`Alt+1-9`	Quick select item
`Ctrl+R` (in UI)	Cycle filter modes

Filter Modes

Mode	Description
`global`	All history across machines
`host`	Current machine only
`session`	Current terminal session
`directory`	Current working directory
`workspace`	Git repository root

Search Modes

Mode	Description
`prefix`	Match from start of command
`fulltext`	Substring match anywhere
`fuzzy`	Fuzzy matching (default)
`skim`	Skim-style fuzzy finder

Command Line Search

bash

# Basic search
atuin search "git push"
 
# Filter by exit code (successful only)
atuin search --exit 0 "make"
 
# Time-based filtering
atuin search --after "yesterday 3pm" "docker"
atuin search --before "2024-01-01" "npm"
 
# Combine filters
atuin search --exit 0 --after "1 week ago" "kubectl"
 
# Directory filter
atuin search --cwd /path/to/project "test"

Sync Setup

Cloud Sync (Atuin Server)

bash

# 1. Register account
atuin register -u <USERNAME> -e <EMAIL>
 
# 2. Login (creates session)
atuin login -u <USERNAME>
 
# 3. Import existing history
atuin import auto
 
# 4. Sync
atuin sync
 
# Check sync status
atuin status

Self-Hosted Server

bash

# Using Docker
docker run -d \
  -p 8888:8888 \
  -v $HOME/.atuin-server:/data \
  ghcr.io/atuinsh/atuin:latest \
  server start
 
# Configure client
atuin config set sync_address "http://localhost:8888"

Sync v2 (Faster)

toml

# ~/.config/atuin/config.toml
[sync]
records = true  # Enable sync v2

Configuration

Config File Location

~/.config/atuin/config.toml    # Main config
~/.local/share/atuin/history.db # History database
~/.local/share/atuin/key        # Encryption key
~/.local/share/atuin/session    # Server session

Essential Settings

toml

# ~/.config/atuin/config.toml
 
# Search behavior
search_mode = "fuzzy"           # prefix, fulltext, fuzzy, skim
filter_mode = "global"          # global, host, session, directory, workspace
 
# Shell key binding defaults
filter_mode_shell_up_key_binding = "session"  # Up arrow default
 
# UI settings
style = "compact"               # auto, full, compact
inline_height = 40              # Max lines (0 = full screen)
show_preview = true             # Show command preview
show_help = true                # Show keybind help
enter_accept = false            # true = execute immediately
 
# Sync settings
auto_sync = true                # Sync automatically
sync_frequency = "1h"           # How often to sync
sync_address = "https://api.atuin.sh"  # Server URL
 
# Privacy
secrets_filter = true           # Auto-filter sensitive data
store_failed = true             # Store failed commands

Privacy Filters

toml

# ~/.config/atuin/config.toml
 
# Regex patterns to exclude from history
history_filter = [
  "^password",
  "^secret",
  "^export.*API_KEY",
  ".*--password.*"
]
 
# Directories to exclude
cwd_filter = [
  "^/tmp",
  "^/private"
]
 
# Built-in secrets filter (AWS keys, tokens, etc.)
secrets_filter = true

Key Bindings

toml

# ~/.config/atuin/config.toml
 
# Vim-style navigation
keymap_mode = "vim-normal"      # emacs, vim-normal, vim-insert, auto
 
# Cursor style per mode
[keymap_cursor]
emacs = "blink-block"
vim_insert = "blink-bar"
vim_normal = "steady-block"

Commands Reference

Core Commands

bash

# History operations
atuin history list              # List all history
atuin history list --cmd-only   # Commands only (no metadata)
atuin history prune             # Remove entries
 
# Search
atuin search [query]            # Interactive search
atuin search --interactive      # Force interactive mode
 
# Sync
atuin sync                      # Manual sync
atuin sync --force              # Force full sync
atuin status                    # Sync status
 
# Statistics
atuin stats                     # Usage statistics
atuin stats --count 20          # Top 20 commands
 
# Account
atuin register                  # Create account
atuin login                     # Login to sync server
atuin logout                    # Logout
atuin account delete            # Delete account
 
# Maintenance
atuin doctor                    # Diagnostic checks
atuin info                      # System information
atuin gen-completions           # Generate shell completions

Import Commands

bash

# Auto-detect and import
atuin import auto
 
# Specific shells
atuin import zsh
atuin import bash
atuin import fish
atuin import resh
 
# Import zsh_history file
atuin import zsh-hist-db

Daemon Mode

bash

# Start daemon (background sync)
atuin daemon
 
# Check daemon status
atuin daemon status

Statistics

View Stats

bash

# Basic stats
atuin stats
 
# Top N commands
atuin stats --count 25
 
# Example output:
# Total commands: 50,234
# Unique commands: 12,456
#
# Top 10:
#  1. git status     (2,345)
#  2. cd             (1,890)
#  3. ls             (1,654)
#  4. git diff       (1,234)
#  ...

Configure Stats

toml

# ~/.config/atuin/config.toml
 
[stats]
# Commands where subcommands matter
common_subcommands = [
  "cargo",
  "git",
  "kubectl",
  "docker",
  "npm"
]
 
# Prefixes to strip from stats
common_prefix = [
  "sudo"
]

Workflows

Daily Development Workflow

bash

# Morning: Sync history from other machines
atuin sync
 
# During work: Search across all history
# Press Ctrl+R, type query
# Use Ctrl+R to cycle: session → directory → global
 
# Find that command you ran last week
atuin search --after "1 week ago" "docker-compose"
 
# Check your patterns
atuin stats

Multi-Machine Workflow

bash

# On Machine A: Register and setup
atuin register -u myuser -e me@example.com
atuin import auto
atuin sync
 
# On Machine B: Login and sync
atuin login -u myuser
atuin sync
 
# History now shared between machines
# Search finds commands from both

Troubleshooting Workflow

bash

# Check installation
atuin doctor
 
# Verify shell integration
echo $ATUIN_SESSION  # Should be set
 
# Test search
atuin search "test"
 
# Check sync status
atuin status
 
# Force resync if needed
atuin sync --force

Performance Tips

Optimize Search Speed

toml

# ~/.config/atuin/config.toml
 
# Use prefix mode for faster matching
search_mode = "prefix"
 
# Limit to session by default
filter_mode = "session"
 
# Reduce preview height
max_preview_height = 2

Reduce Sync Traffic

toml

# ~/.config/atuin/config.toml
 
# Sync less frequently
sync_frequency = "4h"
 
# Enable sync v2 (more efficient)
[sync]
records = true

Daemon Mode (v18.3+)

toml

# ~/.config/atuin/config.toml
 
[daemon]
enabled = true
sync_frequency = 300  # seconds

Migration

From fzf/history

bash

# 1. Install atuin
curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh | sh
 
# 2. Import existing history
atuin import auto
 
# 3. Add shell integration (replaces fzf Ctrl+R)
echo 'eval "$(atuin init zsh)"' >> ~/.zshrc
 
# 4. Remove fzf history binding (if any)
# Remove: bindkey '^R' fzf-history-widget

From Other History Tools

bash

# mcfly: Export first, then import
mcfly export > history.txt
# Manual import needed
 
# hstr: Standard history import works
atuin import auto

Security

Encryption

All sync data is end-to-end encrypted
Server cannot read your history
Key stored locally (~/.local/share/atuin/key)

Key Backup

bash

# Backup your encryption key
cp ~/.local/share/atuin/key ~/atuin-key.backup
 
# Restore on new machine
cp ~/atuin-key.backup ~/.local/share/atuin/key

Secrets Filtering

toml

# ~/.config/atuin/config.toml
 
# Enable automatic secrets filtering
secrets_filter = true  # Blocks AWS keys, GitHub tokens, etc.
 
# Add custom patterns
history_filter = [
  ".*password=.*",
  ".*secret=.*",
  "^mysql.*-p.*"
]

Troubleshooting

Common Issues

Issue	Solution
Ctrl+R not working	Check shell integration in rc file
Sync failing	Run `atuin doctor`, check network
Missing history	Run `atuin import auto`
Slow search	Switch to `prefix` search mode
Duplicate history	Check if imported multiple times

Diagnostic Commands

bash

# Full diagnostics
atuin doctor
 
# System info
atuin info
 
# Check database
sqlite3 ~/.local/share/atuin/history.db "SELECT COUNT(*) FROM history"
 
# Debug mode
ATUIN_LOG=debug atuin sync

Reset Everything

bash

# Logout and clear local data
atuin logout
rm -rf ~/.local/share/atuin
rm -rf ~/.config/atuin
 
# Reinstall
curl --proto '=https' --tlsv1.2 -LsSf https://setup.atuin.sh | sh

References

references/configuration.md - Complete configuration reference with intent-to-config mapping
references/commands.md - Full CLI command reference
references/search-reference.md - Search flags, TUI shortcuts, Vim mode, format variables
references/sync-setup.md - Detailed sync configuration
references/troubleshooting.md - Common issues and fixes
references/workflows.md - Advanced usage patterns
references/tips-and-tricks.md - Power user patterns, fzf coexistence, dotfiles sync, tmux

External Links

Official Docs: https://docs.atuin.sh
GitHub: https://github.com/atuinsh/atuin
Forum: https://forum.atuin.sh
Discord: Community support

Gotchas

Sync over captive-portal Wi-Fi: atuin status reports ok, but inserts buffer locally only. History looks fine until you check on another machine.
Encryption key is per-machine — losing it locks you out of synced history irrecoverably. Back up ~/.local/share/atuin/key.
Search mode `fuzzy` vs `prefix`: match counts differ subtly; switching modes confuses muscle memory at 2am.
Atuin history is NOT shared with shell history file — ~/.zsh_history and atuin's DB drift; history builtin and atuin search return different results.
Self-hosted server needs PostgreSQL — SQLite is single-user only. The error mentioning "embedded mode" doesn't surface the issue clearly.

Security

Security scanPassed, 100 of 100Pattern checks on the skill's files.
Model reviewNot runA model review is scheduled for the next rescan.

See the full security report

Quality evaluation

Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

SKILL.md in the repositoryCheckingskills/atuin/SKILL.md

Popularity

Repository stars: 84
Repository forks: 18
7-day trend score: 22

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

Claude Code
Cursor
GitHub Copilot
Windsurf
Codex
Gemini CLI
Cline
Amp
Roo Code
Goose
Continue
Kilo Code
Junie
Trae
OpenHands
Qwen Code
AI Agent
Tabnine Chat
Sourcegraph Cody
Amazon Q
Firebase Genkit
Sweep
Devin
Phind
Mentat
Claude Desktop
Aider
GPT Pilot
Plandex
bolt.new
v0
Replit Agent
Anse
TypingMind
BetterChatGPT
LibreChat
Warp AI
Pieces
Fig AI

Embed badge

[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/julianobarbosa/claude-code-skills/atuin/badge)](https://verified-skill.com/skills/julianobarbosa/claude-code-skills/atuin)

Something wrong with this skill or its page? Tell us.