Skip to content

feat: add file discovery performance guidance and fd/ripgrep installers #115

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marcusquinn merged 1 commit into from
Jan 17, 2026
Merged

feat: add file discovery performance guidance and fd/ripgrep installers #115

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .agent/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,14 @@ Run pre-edit-check.sh in `~/Git/aidevops/` BEFORE any changes to either location

**Quality Standards**: SonarCloud A-grade, ShellCheck zero violations

**File Discovery** (fastest to slowest):
1. `git ls-files '*.md'` - Instant, git-tracked files only
2. `fd -e md` or `fd -g '*.md'` - Fast, respects .gitignore, Rust-based
3. `rg --files -g '*.md'` - Fast, respects .gitignore (ripgrep)
4. `mcp_glob` tool - Fallback when bash unavailable or for complex patterns

Use `git ls-files` for tracked files (most common). Use `fd` for untracked files or system-wide searches (e.g., `~/.config/`). The `mcp_glob` tool is CPU-intensive on large codebases.

**Localhost Standards** (for any local service setup):
- **Always check port first**: `localhost-helper.sh check-port <port>` before starting services
- **Use .local domains**: `myapp.local` not `localhost:3000` (enables password manager autofill)
Expand Down
24 changes: 22 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -445,13 +445,33 @@ See `.agent/aidevops/architecture.md` for detailed implementation notes and refe

```bash
# Install dependencies (auto-detected by setup.sh)
brew install sshpass jq curl mkcert dnsmasq # macOS
sudo apt-get install sshpass jq curl dnsmasq # Ubuntu/Debian
brew install sshpass jq curl mkcert dnsmasq fd ripgrep # macOS
sudo apt-get install sshpass jq curl dnsmasq fd-find ripgrep # Ubuntu/Debian

# Generate SSH key
ssh-keygen -t ed25519 -C "your-email@domain.com"
```

### **File Discovery Tools**

AI agents use fast file discovery tools for efficient codebase navigation:

| Tool | Purpose | Speed |
|------|---------|-------|
| `fd` | Fast file finder (replaces `find`) | ~10x faster |
| `ripgrep` | Fast content search (replaces `grep`) | ~10x faster |

Both tools respect `.gitignore` by default and are written in Rust for maximum performance.

**Preference order for file discovery:**

1. `git ls-files '*.md'` - Instant, git-tracked files only
2. `fd -e md` - Fast, respects .gitignore
3. `rg --files -g '*.md'` - Fast, respects .gitignore
4. Built-in glob tools - Fallback when bash unavailable

The setup script offers to install these tools automatically.

## **Comprehensive Service Coverage**

### **Infrastructure & Hosting**
Expand Down
104 changes: 104 additions & 0 deletions setup.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -562,6 +562,109 @@ setup_git_clis() {
return 0
}

# Setup file discovery tools (fd, ripgrep) for efficient file searching
setup_file_discovery_tools() {
print_info "Setting up file discovery tools..."

local missing_tools=()
local missing_packages=()
local missing_names=()

# Check for fd (fd-find)
if ! command -v fd >/dev/null 2>&1; then
Copy link
Copy Markdown

@augmentcode augmentcode bot Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On Debian/Ubuntu, fd-find commonly provides the fdfind binary (without fd), but this check only looks for fd and will still report it missing/prompt even when fdfind is already installed.

Fix This in Augment

🤖 Was this useful? React with 👍 or 👎

missing_tools+=("fd")
missing_packages+=("fd")
missing_names+=("fd (fast file finder)")
else
local fd_version
fd_version=$(fd --version 2>/dev/null | head -1 || echo "unknown")
print_success "fd found: $fd_version"
fi
Comment on lines +574 to +582
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Verify fd command availability after fd-find installation on Debian/Ubuntu.

On Debian/Ubuntu, fd-find installs the binary as fdfind, not fd. The check at line 574 (command -v fd) will still fail after installation since the binary name differs.

Consider checking for fdfind as well on apt-based systems, or updating the success message to be more accurate.

🔧 Suggested improvement 
     # Check for fd (fd-find)
-    if ! command -v fd >/dev/null 2>&1; then
+    if ! command -v fd >/dev/null 2>&1 && ! command -v fdfind >/dev/null 2>&1; then
         missing_tools+=("fd")
         missing_packages+=("fd")
         missing_names+=("fd (fast file finder)")
     else
         local fd_version
-        fd_version=$(fd --version 2>/dev/null | head -1 || echo "unknown")
+        fd_version=$(fd --version 2>/dev/null || fdfind --version 2>/dev/null | head -1 || echo "unknown")
         print_success "fd found: $fd_version"
     fi
🤖 Prompt for AI Agents 
In `@setup.sh` around lines 574 - 582, The check currently looks only for the fd
executable (command -v fd) so on Debian/Ubuntu systems where the package
installs fdfind it will still be reported missing; update the logic around the
fd check to also probe for fdfind, set fd_version by calling whichever binary
exists (fd or fdfind) and call print_success accordingly, and if only fdfind is
found ensure missing_packages/missing_names reflect the apt package name
"fd-find" or map fdfind to the canonical "fd" name in missing_tools; reference
the existing identifiers fd_version, missing_tools, missing_packages,
missing_names, and print_success when making the change.


# Check for ripgrep
if ! command -v rg >/dev/null 2>&1; then
missing_tools+=("rg")
missing_packages+=("ripgrep")
missing_names+=("ripgrep (fast content search)")
else
local rg_version
rg_version=$(rg --version 2>/dev/null | head -1 || echo "unknown")
print_success "ripgrep found: $rg_version"
fi
Comment on lines +573 to +593
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The current implementation checks for fd and ripgrep in separate blocks of code. This can be refactored into a data-driven loop to improve maintainability and make it easier to add more tools in the future. By defining the tools in an array, you can iterate through them, reducing code duplication and making the logic more scalable.

Suggested change
# Check for fd (fd-find)
if ! command -v fd >/dev/null 2>&1; then
missing_tools+=("fd")
missing_packages+=("fd")
missing_names+=("fd (fast file finder)")
else
local fd_version
fd_version=$(fd --version 2>/dev/null | head -1 || echo "unknown")
print_success "fd found: $fd_version"
fi
# Check for ripgrep
if ! command -v rg >/dev/null 2>&1; then
missing_tools+=("rg")
missing_packages+=("ripgrep")
missing_names+=("ripgrep (fast content search)")
else
local rg_version
rg_version=$(rg --version 2>/dev/null | head -1 || echo "unknown")
print_success "ripgrep found: $rg_version"
fi
local tools_to_check=(
"fd:fd:fd (fast file finder)"
"rg:ripgrep:ripgrep (fast content search)"
)
for tool_info in "${tools_to_check[@]}"; do
IFS=':' read -r cmd pkg_name friendly_name <<< "$tool_info"
if ! command -v "$cmd" >/dev/null 2>&1; then
missing_tools+=("$cmd")
missing_packages+=("$pkg_name")
missing_names+=("$friendly_name")
else
local version
version=$($cmd --version 2>/dev/null | head -1 || echo "unknown")
print_success "$friendly_name found: $version"
fi
done


# Offer to install missing tools
if [[ ${#missing_tools[@]} -gt 0 ]]; then
print_warning "Missing file discovery tools: ${missing_names[*]}"
echo ""
echo " These tools provide 10x faster file discovery than built-in glob:"
echo " fd - Fast alternative to 'find', respects .gitignore"
echo " ripgrep - Fast alternative to 'grep', respects .gitignore"
echo ""
echo " AI agents use these for efficient codebase navigation."
echo ""

local pkg_manager
pkg_manager=$(detect_package_manager)

if [[ "$pkg_manager" != "unknown" ]]; then
read -r -p "Install file discovery tools (${missing_packages[*]}) using $pkg_manager? (y/n): " install_fd_tools

if [[ "$install_fd_tools" == "y" ]]; then
print_info "Installing ${missing_packages[*]}..."

# Handle package name differences across package managers
local actual_packages=()
for pkg in "${missing_packages[@]}"; do
case "$pkg_manager" in
Copy link
Copy Markdown

@augmentcode augmentcode bot Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The install mapping only rewrites fd→fd-find for apt, but your manual instructions say Fedora uses fd-find; with dnf (and potentially yum) this will try to install fd and may fail.

Fix This in Augment

🤖 Was this useful? React with 👍 or 👎

apt)
# Debian/Ubuntu uses fd-find instead of fd
if [[ "$pkg" == "fd" ]]; then
actual_packages+=("fd-find")
else
actual_packages+=("$pkg")
fi
;;
*)
actual_packages+=("$pkg")
;;
esac
done

if install_packages "$pkg_manager" "${actual_packages[@]}"; then
print_success "File discovery tools installed"

# On Debian/Ubuntu, fd is installed as fdfind - create alias
if [[ "$pkg_manager" == "apt" ]] && command -v fdfind >/dev/null 2>&1 && ! command -v fd >/dev/null 2>&1; then
print_info "Note: On Debian/Ubuntu, fd is installed as 'fdfind'"
echo " Consider adding to your shell config: alias fd=fdfind"
fi
else
print_warning "Failed to install some file discovery tools (non-critical)"
fi
else
print_info "Skipped file discovery tools installation"
echo ""
echo " Manual installation:"
echo " macOS: brew install fd ripgrep"
echo " Ubuntu/Debian: sudo apt install fd-find ripgrep"
echo " Fedora: sudo dnf install fd-find ripgrep"
echo " Arch: sudo pacman -S fd ripgrep"
fi
else
echo ""
echo " Manual installation:"
echo " macOS: brew install fd ripgrep"
echo " Ubuntu/Debian: sudo apt install fd-find ripgrep"
echo " Fedora: sudo dnf install fd-find ripgrep"
echo " Arch: sudo pacman -S fd ripgrep"
fi
Comment on lines +609 to +660
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The code block for printing manual installation instructions is duplicated. This can be refactored to avoid repetition, which improves maintainability. By restructuring the logic, you can have a single block that handles the case where automatic installation is not possible or was skipped by the user.

        local attempt_install=false
        if [[ "$pkg_manager" != "unknown" ]]; then
            read -r -p "Install file discovery tools (${missing_packages[*]}) using $pkg_manager? (y/n): " install_fd_tools
            if [[ "$install_fd_tools" == "y" ]]; then
                attempt_install=true
            fi
        fi

        if [[ "$attempt_install" == "true" ]]; then
            print_info "Installing ${missing_packages[*]}..."
            
            # Handle package name differences across package managers
            local actual_packages=()
            for pkg in "${missing_packages[@]}"; do
                case "$pkg_manager" in
                    apt)
                        # Debian/Ubuntu uses fd-find instead of fd
                        if [[ "$pkg" == "fd" ]]; then
                            actual_packages+=("fd-find")
                        else
                            actual_packages+=("$pkg")
                        fi
                        ;;
                    *)
                        actual_packages+=("$pkg")
                        ;;
                esac
            done
            
            if install_packages "$pkg_manager" "${actual_packages[@]}"; then
                print_success "File discovery tools installed"
                
                # On Debian/Ubuntu, fd is installed as fdfind - create alias
                if [[ "$pkg_manager" == "apt" ]] && command -v fdfind >/dev/null 2>&1 && ! command -v fd >/dev/null 2>&1; then
                    print_info "Note: On Debian/Ubuntu, fd is installed as 'fdfind'"
                    echo "  Consider adding to your shell config: alias fd=fdfind"
                fi
            else
                print_warning "Failed to install some file discovery tools (non-critical)"
            fi
        else
            if [[ "$pkg_manager" != "unknown" ]]; then
                print_info "Skipped file discovery tools installation"
            fi
            echo ""
            echo "  Manual installation:"
            echo "    macOS:        brew install fd ripgrep"
            echo "    Ubuntu/Debian: sudo apt install fd-find ripgrep"
            echo "    Fedora:       sudo dnf install fd-find ripgrep"
            echo "    Arch:         sudo pacman -S fd ripgrep"
        fi

else
print_success "All file discovery tools installed!"
fi

return 0
}

# Setup Worktrunk - Git worktree management for parallel AI agent workflows
setup_worktrunk() {
print_info "Setting up Worktrunk (git worktree management)..."
Expand Down Expand Up @@ -2439,6 +2542,7 @@ main() {
confirm_step "Check optional dependencies (bun, node, python)" && check_optional_deps
confirm_step "Setup recommended tools (Tabby, Zed, etc.)" && setup_recommended_tools
confirm_step "Setup Git CLIs (gh, glab, tea)" && setup_git_clis
confirm_step "Setup file discovery tools (fd, ripgrep)" && setup_file_discovery_tools
confirm_step "Setup Worktrunk (git worktree management)" && setup_worktrunk
confirm_step "Setup SSH key" && setup_ssh_key
confirm_step "Setup configuration files" && setup_configs
Expand Down
Loading