opencode-fff-search

OpenCode plugin that replaces the default grep and glob file search tools with fff.nvim's ultra-fast, typo-resistant search engine.

Features

• Blazing fast - In-memory index, searches complete in milliseconds
• Typo-resistant - Fuzzy matching handles typos gracefully
• Smart mode - Auto-selects between literal (SIMD) and regex matching based on pattern content; plain text with parentheses, dots, and commas matches correctly. Now correctly identifies escaped regex characters like \., \(, and \) as regex triggers.
• Improved Path Filtering - Correctly handles . (current directory), absolute paths, and root slashes by searching the entire project instead of returning empty results.
• Git-aware - Shows file status (modified, staged, untracked)
• Smart case - Auto-detects case sensitivity
• Zero config - Works out of the box

Prerequisites

• OpenCode 1.14+
• Node.js 18+ (or Bun)
• Cross-platform: Linux, macOS, Windows (WSL recommended for Windows)

Installation

Option 1: Manual Installation (All Platforms)

1. Copy the plugin to your OpenCode plugins directory:

   Linux/macOS:

   mkdir -p ~/.config/opencode/plugins
   cp index.js ~/.config/opencode/plugins/opencode-fff-search.js

   Windows (PowerShell):

   New-Item -ItemType Directory -Force "$env:APPDATA\opencode\plugins"
   Copy-Item index.js "$env:APPDATA\opencode\plugins\opencode-fff-search.js"

   Or project-specific (any OS):

   mkdir -p /path/to/project/.opencode/plugins
   cp index.js /path/to/project/.opencode/plugins/

2. Install dependencies:

   Navigate to your OpenCode config directory and install:

   Linux/macOS:

   cd ~/.config/opencode  # or ~/.opencode for project-local
   bun install            # or: npm install

   Windows:

   cd "$env:APPDATA\opencode"
   bun install
   # or: npm install

   This installs @ff-labs/fff-node and downloads the platform-specific fff binary automatically.

Option 2: Using the install script

git clone https://github.com/ozgurulukir/opencode-fff-search.git
cd opencode-fff-search
./install.sh  # Works on Linux/macOS

For Windows, run the equivalent commands manually or use WSL.

Option 3: From npm (published)

Add to your OpenCode config (opencode.json or opencode.jsonc):

{
  "plugin": ["opencode-fff-search"]
}

OpenCode will auto-install the plugin and its dependencies on next startup.

Alternatively, install globally:

npm install -g opencode-fff-search

Verification

Restart OpenCode and run:

opencode run "Search for 'import' using grep"

You should notice faster search results. Check debug logs if needed:

opencode debug config --print-logs 2>&1 | grep fff

How It Works

This plugin overrides OpenCode's built-in grep and glob tools. When the AI (or user) performs file search, it uses fff's in-memory index instead of spawning ripgrep processes.

• grep -> fff's content search with auto mode detection — plain literal (SIMD) by default, automatically switches to regex when the pattern contains intentional regex syntax (\s, |, [0-9], etc.).
• Results are fetched across multiple "pages" of files (cursor-based pagination) until the requested limit is met or no more results exist
• glob -> fff's fuzzy file finder

Note: Memory-mapped file caching (mmap) and the frecency database (LMDB) are disabled to prevent SIGBUS crashes. fff's mmap warmup maps all indexed files into memory, which causes an unrecoverable bus error when any mapped file is truncated or deleted during a session (editor saves, git operations, builds). Standard file I/O is used instead, with negligible performance impact for agent workloads where the index scan dominates latency. The file watcher is temporarily disabled due to an upstream stack overflow bug in fff-node v0.6.4 (fff.nvim#422). New files created during a session will not appear in search until OpenCode restarts. See SIGBUS_INVESTIGATION.md for full root cause analysis.

Tool Parameters

grep Tool

Search file contents with fff's fast, typo-resistant search.

| Parameter | Type | Required? | Default | Description | |-----------|------|-----------|---------|-------------| | pattern | string | Yes | — | Search pattern (literal or regex — auto-detected) | | path | string | No | — | Subdirectory or file to search within. Supports . for project root. | | exclude | string | No | — | Comma-separated glob patterns to exclude (e.g., "*.log,node_modules/**") | | caseSensitive | boolean | No | false (smart-case) | Enable case-sensitive matching | | context | number | No | 0 | Number of lines before/after match to include | | limit | number | No | 1000 | Maximum total matches to return |

Search mode auto-detection: The plugin automatically selects the matching engine:

• Plain (SIMD) — Used by default. Fast, literal matching. Handles patterns with parentheses, dots, commas, and other code symbols that regex engines fail on.
• Regex — Automatically activated when the pattern contains intentional regex syntax: \s, \d, |, [...], ^, $, escaped quantifiers, or escaped characters like \., \(, \).

If plain mode returns no results, the plugin retries with regex mode as a fallback.

Smart-case behavior: By default (caseSensitive: false), fff auto-detects case sensitivity—if the pattern contains uppercase letters, it becomes case-sensitive.

Examples:

# Simple search
opencode run "Search for 'import' using grep"

# Case-sensitive search in src directory, excluding node_modules
opencode run "Search for 'TODO' using grep with {\"path\": \"src\", \"caseSensitive\": true, \"exclude\": \"*.test.js\"}"

# Get context lines around matches
opencode run "Search for 'function' using grep with {\"context\": 3}"

# Limit results to first 50 matches
opencode run "Search for 'console.log' using grep with {\"limit\": 50}"

glob Tool

Find files and directories using fff's fuzzy search.

| Parameter | Type | Required? | Default | Description | |-----------|------|-----------|---------|-------------| | pattern | string | Yes | — | Search pattern (fuzzy, glob, or plain text) | | path | string | No | — | Subdirectory to search within | | type | "file" \| "directory" | No | "file" | Filter results by type | | limit | number | No | 100 | Maximum number of results |

Examples:

# Find all JavaScript files
opencode run "Find files matching '*.js' using glob"

# Find directories only
opencode run "Find files matching 'src' using glob with {\"type\": \"directory\"}"

# Search within a subdirectory
opencode run "Find files matching 'config' using glob with {\"path\": \"src\"}"

# Increase result limit
opencode run "Find files matching '*' using glob with {\"limit\": 500}"

Performance

On a Chromium-sized repo (500k files):

| Operation | ripgrep (spawn) | fff (warm cache) | |-----------|----------------|------------------| | Single search | 3-9s | <10ms | | 100 searches | 5-15min | <1s |

Mmap caching and the LMDB frecency database are disabled for stability; the file watcher is temporarily disabled due to an upstream stack overflow bug (fff.nvim#422). Search latency averages 6ms (grep) and 6.5ms (glob) on a 48K-file repo.

Read the full fff.nvim performance analysis

Platform-Specific Notes

Windows

• WSL recommended for best OpenCode experience
• Native Windows works but ensure Node.js is in PATH
• fff binary: @ff-labs/fff-bin-win32-x64 (or -arm64 for ARM)

macOS

• Works on both Intel (x64) and Apple Silicon (arm64)
• fff binaries auto-download: @ff-labs/fff-bin-darwin-x64 or -arm64

Linux

• Multiple variants supported (GNU, musl)
• Auto-detects correct binary via npm optional dependencies

Troubleshooting

Plugin not loading

• Ensure plugin file is in correct plugins/ directory (check with find ~/.config/opencode/plugins)
• Verify ~/.config/opencode/package.json has "type": "module" (required for ESM imports)
• Check dependencies installed: ls ~/.config/opencode/node_modules/@ff-labs/fff-node
• For development, symlink the plugin for live updates:

  ln -sf $(pwd)/index.js ~/.config/opencode/plugins/opencode-fff-search.js

Plugin not updating after upgrade

If the plugin seems to use old behavior after an upgrade, try starting a fresh opencode session instead of continuing an existing one (opencode -c). Node.js caches ES modules per process, so a continued session may still have the previous version loaded.

"Binary not found" errors

The fff native library didn't download. Install manually:

# Linux x64 (most common)
npm install @ff-labs/fff-bin-linux-x64-gnu

# macOS Intel
npm install @ff-labs/fff-bin-darwin-x64

# macOS Apple Silicon
npm install @ff-labs/fff-bin-darwin-arm64

# Windows x64 (in WSL or native)
npm install @ff-labs/fff-bin-win32-x64

See all platform packages.

Slow first search

The first search triggers index building (typically 500ms-2s depending on repo size). Subsequent searches are instant. The index persists in memory while OpenCode runs.

Permission errors

• Ensure you have read access to the project directory
• On Linux/macOS: check file permissions
• On Windows: run terminal as admin if accessing protected directories

SIGBUS crashes (signal 7)

WARNING: fff-node v0.6.4 has an upstream stack overflow bug in grep processing (fff.nvim#422) that cannot be prevented by plugin configuration. The crash occurs in libfff_c.so native code during grep on large projects. The plugin should not be used in production until upstream ships a fix.

All configurable safety options are at maximum:

• disableMmapCache: true — no file content mmap
• aiMode: false — no LMDB frecency database
• disableContentIndexing: true — no content index buffers
• disableWatch: true — no file system watcher threads

See CRASH_REPORT_v0.6.4.md for full analysis.

Development

git clone https://github.com/ozgurulukir/opencode-fff-search.git
cd opencode-fff-search
npm install

# Run the automated test suite (85 core unit tests)
node --test test/index.test.js

# Run session simulation tests (synthetic project stress tests)
node --test test/session-*.js

# Run integration tests (requires opencode CLI + plugin symlinked)
node --test test/integration-*.js

# Test the plugin loads correctly
node -e "import('./index.js').then(m => console.log('Plugin loads OK'))"

MIT - see [LICENSE](LICENSE) file.

## Credits

- [fff.nvim](https://github.com/dmtrKovalenko/fff.nvim) - Fast file finder library
- [OpenCode](https://github.com/anomalyco/opencode) - AI coding agent

## Contributing
PRs welcome! Please:

1. Run the test suite: `node --test test/index.test.js`
2. Run session stress tests: `node --test test/session-*.js`
3. Test with a real OpenCode session
4. Include benchmark results if optimizing performance
5. Follow existing code style (no semicolons, 2-space indent)
6. Update README if changing behavior

## Related

- [fff.nvim GitHub](https://github.com/dmtrKovalenko/fff.nvim) - The underlying search engine
- [OpenCode Plugins Docs](https://opencode.ai/docs/plugins) - Plugin development guide
- [OpenCode Ecosystem](https://opencode.ai/docs/ecosystem) - Other community plugins