Hoards

AI-powered CLI tool manager with usage analytics and multi-source tracking.

"Know what you use. Discover what you need."

Hoards tracks your CLI tools across multiple package managers, provides usage analytics from shell history, and offers AI-powered categorization and discovery.

Features

• Terminal UI (TUI) - Rich visual interface with fuzzy search, vim keybindings, and mouse support
• Multi-source tracking - Track tools from cargo, apt, pip, npm, brew, flatpak
• Usage analytics - Parse shell history (Fish, Bash, Zsh) to see which tools you actually use
• AI integration - Auto-categorize tools and generate descriptions using Claude, Gemini, or Codex
• GitHub sync - Fetch repository info, topics, and stars
• Bundles - Group related tools for batch installation
• Config management - Track dotfiles and tool configurations
• 6 built-in themes - Catppuccin, Dracula, Nord, Tokyo Night, Gruvbox, plus custom themes

Terminal UI

Launch the TUI for visual tool management:

hoards tui    # or just: hoards

Highlights:

• 5 tabs: Installed, Available, Updates, Bundles, Discover
• Fuzzy search: Press / to filter tools instantly
• Vim navigation: j/k/g/G and arrow keys
• Multi-select: Space to select, Ctrl+a for all
• Command palette: : for vim-style commands
• Theme cycling: Press t to change themes
• Mouse support: Click tabs, scroll lists, right-click to select

See the TUI Guide for complete documentation.

Installation

# From crates.io
cargo install hoards

# From source
git clone https://github.com/chrisbataille/hoards.git
cd hoards
cargo install --path .

Quick Start

# First-time setup (interactive wizard)
hoards init

# Or manually:
hoards sync --scan          # Scan system for tools
hoards sync --github        # Fetch GitHub data
hoards sync --usage         # Parse shell history
hoards sync --all           # Do everything

# Daily maintenance
hoards maintain             # Quick health check + sync

# See what you have
hoards discover list        # List all tools
hoards insights overview    # Usage stats dashboard

Commands

Workflow Commands

Sync

hoards sync                 # Sync installation status
hoards sync --scan          # Include tool discovery
hoards sync --github        # Include GitHub data
hoards sync --usage         # Include usage tracking
hoards sync --descriptions  # Fetch descriptions
hoards sync --all           # Everything

Discover

hoards discover list                # List all tools
hoards discover search <query>      # Search tools
hoards discover categories          # Browse by category
hoards discover labels              # Browse by label
hoards discover missing             # Tools you might want
hoards discover recommended         # Based on your usage
hoards discover similar <tool>      # Find related tools
hoards discover trending            # Popular tools (GitHub stars)

Insights

hoards insights overview            # Dashboard
hoards insights usage [tool]        # Usage statistics
hoards insights unused              # Tools you never use
hoards insights health              # Database health check
hoards insights stats               # Database statistics

Usage Tracking

Two modes for tracking tool usage:

# Configure tracking mode
hoards usage config                 # View current mode
hoards usage config --mode scan     # Manual history scanning
hoards usage config --mode hook     # Real-time shell hooks (recommended)

# With hook mode, also run:
hoards usage init                   # Set up shell hooks automatically

# Manual commands
hoards usage scan                   # Scan shell history
hoards usage show                   # Show usage stats
hoards usage tool <name>            # Usage for specific tool
hoards usage reset                  # Reset all counters

Shell Completions

hoards completions status           # Show completion status for all shells
hoards completions install          # Install for detected shells
hoards completions install fish     # Install for specific shell
hoards completions uninstall        # Remove all completions

Supported shells: Fish, Bash, Zsh. Completions are auto-installed during hoards init.

Tool Management

Bundles

hoards bundle create <name> <tools...>   # Create bundle
hoards bundle list                        # List bundles
hoards bundle show <name>                 # Show contents
hoards bundle install <name>              # Install all tools
hoards bundle add <name> <tools...>       # Add tools
hoards bundle remove <name> <tools...>    # Remove tools
hoards bundle delete <name>               # Delete bundle

AI Features

# Configuration
hoards ai config set <provider>     # Set provider (claude, gemini, codex)
hoards ai config show               # Show current config
hoards ai config test               # Test connection

# Enrichment
hoards ai enrich                    # Interactive menu
hoards ai enrich --categorize       # Auto-categorize tools
hoards ai enrich --describe         # Generate descriptions
hoards ai enrich --all              # Both operations

# Extract from GitHub README
hoards ai extract <github-url>      # Extract tool info from README
hoards ai extract url1 url2 url3    # Batch mode
hoards ai extract url --yes         # Skip confirmation

# Smart Bundle Suggestions
hoards ai suggest-bundle            # AI suggests bundles based on usage
hoards ai suggest-bundle --count 3  # Suggest 3 bundles

# Tool Cheatsheets
hoards ai cheatsheet <tool>         # Generate quick reference
hoards ai cheatsheet ripgrep        # Example: ripgrep cheatsheet
hoards ai cheatsheet git --refresh  # Regenerate cached cheatsheet

# Contextual Discovery
hoards ai discover "<query>"        # Find tools for your workflow
hoards ai discover "kubernetes dev" # Example: K8s development tools
hoards ai discover "data science" --limit 5  # Limit results
hoards ai discover "rust cli" --dry-run      # Show without prompting

Config Management

hoards config link <name> --source <path> --target <path>
hoards config list                  # List managed configs
hoards config sync                  # Create symlinks
hoards config status                # Check symlink status

Configuration

Database Location

• Linux: ~/.local/share/hoards/hoards.db
• macOS: ~/Library/Application Support/hoards/hoards.db

Config Files

~/.config/hoards/
├── config.toml           # Main configuration
├── prompts/              # Custom AI prompts
└── topic-mapping.toml    # GitHub topic → category mapping

AI Setup

# Set your preferred AI provider
hoards ai config set claude

# Test the connection
hoards ai config test

Examples

Track a New Tool

hoards add ripgrep \
  --description "Fast grep replacement written in Rust" \
  --category search \
  --source cargo \
  --binary rg

Create a Bundle

# Create a bundle of modern Unix tools
hoards bundle create modern-unix ripgrep fd bat eza zoxide \
  --description "Modern replacements for classic Unix tools"

# Install everything
hoards bundle install modern-unix

Find Unused Tools

# Scan usage first
hoards sync --usage

# Find tools you never use
hoards insights unused

# Clean up
hoards cleanup

Development

# Clone
git clone https://github.com/chrisbataille/hoards.git
cd hoards

# Enable pre-commit hooks
git config core.hooksPath .githooks

# Build & test
cargo build
cargo test
cargo clippy

See CONTRIBUTING.md for development workflow.

License

MIT License - see LICENSE for details.