version: "1.0.1" name: file-suggestion description: Set up fast file suggestions for Claude Code using ripgrep, jq, and fzf. Use this skill when users want to improve file autocomplete performance or add custom file suggestion behavior.

File Suggestion Setup

This skill helps you configure Claude Code's file suggestion feature with a custom script that uses ripgrep, jq, and fzf for fast fuzzy file matching.

Prerequisites

Install these tools before setup:

# Ubuntu/Debian
sudo apt install ripgrep jq fzf
 
# macOS
brew install ripgrep jq fzf
 
# Arch Linux
sudo pacman -S ripgrep jq fzf

Setup Steps

1. Create the Script

Create the file suggestion script at ~/.claude/file-suggestion.sh:

#!/bin/bash
# Custom file suggestion script for Claude Code
# Uses rg + fzf for fuzzy matching and symlink support
 
# Parse JSON input to get query
QUERY=$(jq -r '.query // ""')
 
# Use project dir from env, fallback to pwd
PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
 
# cd into project dir so rg outputs relative paths
cd "$PROJECT_DIR" || exit 1
 
{
  # Main search - respects .gitignore, includes hidden files, follows symlinks
  rg --files --follow --hidden . 2>/dev/null
 
  # Additional paths - include even if gitignored (uncomment and customize)
  # [ -e .notes ] && rg --files --follow --hidden --no-ignore-vcs .notes 2>/dev/null
} | sort -u | fzf --filter "$QUERY" | head -15

2. Make It Executable

chmod +x ~/.claude/file-suggestion.sh

3. Configure Claude Code

Add this to your ~/.claude/settings.json:

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

How It Works

The script:

1. Receives JSON input with a query field from Claude Code
2. Uses ripgrep (rg --files) to list files fast, respecting .gitignore
3. Follows symlinks with --follow flag
4. Includes hidden files with --hidden flag
5. Fuzzy filters results using fzf --filter
6. Returns top 15 matches sorted by relevance

Customization

Include Gitignored Paths

Uncomment and customize the additional paths section:

# Include .notes directory even if gitignored
[ -e .notes ] && rg --files --follow --hidden --no-ignore-vcs .notes 2>/dev/null
 
# Include vendor directory
[ -e vendor ] && rg --files --follow --hidden --no-ignore-vcs vendor 2>/dev/null

Exclude Patterns

Add ripgrep glob patterns to exclude files:

rg --files --follow --hidden \
   --glob '!*.min.js' \
   --glob '!*.map' \
   --glob '!node_modules' \
   . 2>/dev/null

Change Result Limit

Modify the head -15 to return more or fewer results:

# Return top 25 matches
... | head -25

Troubleshooting

Script Not Found

Ensure the path in settings.json matches your script location and uses ~ or absolute path.

No Results

Check that:

• ripgrep is installed: which rg
• fzf is installed: which fzf
• jq is installed: which jq
• Script is executable: ls -la ~/.claude/file-suggestion.sh

Slow Performance

If you have a large repo:

• Ensure .gitignore excludes node_modules, dist, etc.
• Add explicit --glob '!pattern' exclusions for large directories

Template Script

A ready-to-use template is available at:

${CLAUDE_PLUGIN_ROOT}/skills/file-suggestion/scripts/file-suggestion.sh

Copy it to your ~/.claude/ directory and customize as needed.