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.