🦞 FilePulse-CLI

Lightweight Terminal Intelligent File Search Engine 轻量级终端智能文件搜索引擎

🌐 简体中文 | 繁體中文 | 🇺🇸 English

🔥 AI时代的文件搜索引擎 — 基于Frecency记忆排序的智能文件搜索，让AI Agent和开发者在海量代码中精准定位目标文件，越用越聪明。

🇨🇳 简体中文

🎉 项目介绍

FilePulse-CLI 是一款零外部依赖的轻量级终端智能文件搜索引擎。灵感来源于GitHub Trending热门项目 fff，我们独立自研了纯Python实现，并做了大量差异化优化。

解决的核心痛点：

• 🔍 每次搜索都从零开始，没有"记忆"——传统工具（ripgrep/fzf）无法学习你的使用习惯

• 🤖 AI Agent在大型代码库中搜索效率低下，需要多次往返才能找到目标文件

• 📁 Git仓库中已修改的文件无法被优先展示

• 🌏 中文路径和文件名支持不佳

自研差异化亮点：

• 🧠 Frecency记忆排序 — 基于频率×最近性的指数衰减算法，越常用越靠前

• 🎯 拼写容错模糊搜索 — 子序列匹配+Levenshtein距离，输入"mn"也能找到"main.py"

• 🔀 Git状态感知 — 自动检测已修改/已添加文件并提升排名

• 🤖 MCP Server模式 — 原生支持AI Agent集成（Claude Code/Cursor/Windsurf）

• 📊 TUI交互式仪表盘 — 实时展示文件分布、Frecency排行、Git状态

• 🌏 中文路径优化 — 完整支持CJK字符的模糊匹配

• 📤 多格式导出 — 支持JSON/CSV/Markdown结果导出

• 🚫 零外部依赖 — 纯Python标准库实现，开箱即用

✨ 核心特性

🚀 快速开始

环境要求：

• Python 3.8 或更高版本

• 无需安装任何外部依赖

安装方式：

# 方式一：直接克隆运行（推荐）
git clone https://github.com/gitstq/FilePulse-CLI.git
cd FilePulse-CLI
PYTHONPATH=src python -m filepulse --help

# 方式二：使用 pip 安装
pip install .
filepulse --help

基本使用：

# 搜索文件名
filepulse search "main.py"

# 模糊搜索（默认开启）
filepulse search "mn" --fuzzy

# 搜索文件内容
filepulse search "def hello" --content

# 按文件类型过滤
filepulse search "config" --type json

# Git感知搜索（优先展示已修改文件）
filepulse search "utils" --git

# 限制搜索深度
filepulse search "test" --depth 2

# JSON输出
filepulse search "readme" --json

# 导出结果
filepulse search "model" --export results.csv

📖 详细使用指南

搜索模式

# 📁 文件名搜索（默认）
filepulse search "app.py"

# 📝 内容搜索（在文件内容中查找）
filepulse search "import flask" --content

# 🎯 精确搜索（禁用模糊匹配）
filepulse search "exact_name" --no-fuzzy

过滤与排序

# 按扩展名过滤
filepulse search "index" --type ts
filepulse search "component" --type-list "tsx,jsx,vue"

# 按大小过滤
filepulse search "log" --min-size 1KB --max-size 10MB

# 包含隐藏文件
filepulse search "config" --hidden

# 自定义忽略模式
filepulse search "test" --ignore "dist,build,.cache"

# 排序方式：frecency / name / size / modified / relevance
filepulse search "main" --sort size

TUI仪表盘

# 启动交互式仪表盘
filepulse dashboard

# 指定目录和刷新间隔
filepulse dashboard --path /your/project --refresh 5

MCP Server（AI Agent集成）

# 启动HTTP模式MCP Server
filepulse mcp --host 127.0.0.1 --port 8734

# 启动stdio模式（用于直接Agent集成）
filepulse mcp --stdio

MCP工具列表：

• search_files — 按文件名搜索（支持模糊匹配）

• search_content — 按文件内容搜索

• get_file_info — 获取文件详细信息

• list_directory — 列出目录内容

• get_frecency_stats — 获取Frecency统计

Frecency统计

# 查看搜索统计
filepulse stats

# 查看Top 20文件
filepulse stats --top 20

# JSON格式输出
filepulse stats --json

# 清除Frecency数据
filepulse stats --clear

💡 设计思路与迭代规划

设计理念： FilePulse-CLI的核心设计理念是"有记忆的搜索"。传统搜索工具每次都从零开始，而FilePulse通过Frecency算法学习用户的使用模式——你经常访问的文件会自动获得更高的排名。这使得搜索结果随着使用越来越精准，特别适合在大型项目中日常使用。

技术选型原因：

• 纯Python标准库 — 零依赖策略确保在任何Python环境下都能直接运行，无需担心版本冲突或网络问题

• Frecency算法 — 参考Firefox的Frecency实现，使用指数衰减函数平衡频率和最近性两个维度

• MCP协议 — 采用JSON-RPC 2.0标准协议，确保与主流AI Agent的兼容性

后续迭代计划：

• 增量文件监听（inotify/FSEvents）

• 正则表达式搜索模式

• 文件内容预览功能

• 多仓库联合搜索

• 搜索历史记录与回溯

• Web UI仪表盘

• 插件系统（自定义搜索后端）

📦 打包与部署指南

作为Python包安装：

# 从源码安装
git clone https://github.com/gitstq/FilePulse-CLI.git
cd FilePulse-CLI
pip install .

# 验证安装
filepulse --version

作为独立脚本使用：

# 无需安装，直接运行
git clone https://github.com/gitstq/FilePulse-CLI.git
cd FilePulse-CLI
PYTHONPATH=src python -m filepulse search "your-query"

兼容环境：

• Python 3.8, 3.9, 3.10, 3.11, 3.12

• Windows 10+, macOS 10.15+, Linux (主流发行版)

• 无需GPU、无需网络连接

🤝 贡献指南

欢迎贡献代码！请阅读 CONTRIBUTING.md 了解详情。

快速开始：

1. Fork 本仓库

2. 创建特性分支 (git checkout -b feature/your-feature)

3. 提交更改 (git commit -m 'feat: add your feature')

4. 推送到分支 (git push origin feature/your-feature)

5. 发起 Pull Request

📄 开源协议

本项目基于 MIT License 开源。

Related MCP server: mcp-everything-search

🇹🇼 繁體中文

🎉 專案介紹

FilePulse-CLI 是一款零外部依賴的輕量級終端智能檔案搜尋引擎。靈感來源於GitHub Trending熱門項目 fff，我們獨立自研了純Python實現，並做了大量差異化優化。

解決的核心痛點：

• 🔍 每次搜尋都從零開始，沒有「記憶」——傳統工具（ripgrep/fzf）無法學習你的使用習慣

• 🤖 AI Agent在大型程式碼庫中搜尋效率低下，需要多次往返才能找到目標檔案

• 📁 Git倉庫中已修改的檔案無法被優先展示

• 🌏 中文路徑和檔案名支援不佳

自研差異化亮點：

• 🧠 Frecency記憶排序 — 基於頻率×最近性的指數衰減演算法，越常用越靠前

• 🎯 拼寫容錯模糊搜尋 — 子序列匹配+Levenshtein距離，輸入「mn」也能找到「main.py」

• 🔀 Git狀態感知 — 自動偵測已修改/已新增檔案並提升排名

• 🤖 MCP Server模式 — 原生支援AI Agent整合（Claude Code/Cursor/Windsurf）

• 📊 TUI互動式儀表板 — 即時展示檔案分佈、Frecency排行、Git狀態

• 🌏 中文路徑優化 — 完整支援CJK字元的模糊匹配

• 📤 多格式匯出 — 支援JSON/CSV/Markdown結果匯出

• 🚫 零外部依賴 — 純Python標準庫實現，開箱即用

✨ 核心特性

🚀 快速開始

環境要求：

• Python 3.8 或更高版本

• 無需安裝任何外部依賴

安裝方式：

# 方式一：直接克隆運行（推薦）
git clone https://github.com/gitstq/FilePulse-CLI.git
cd FilePulse-CLI
PYTHONPATH=src python -m filepulse --help

# 方式二：使用 pip 安裝
pip install .
filepulse --help

基本使用：

# 搜尋檔案名
filepulse search "main.py"

# 模糊搜尋（預設開啟）
filepulse search "mn" --fuzzy

# 搜尋檔案內容
filepulse search "def hello" --content

# 按檔案類型過濾
filepulse search "config" --type json

# Git感知搜尋（優先展示已修改檔案）
filepulse search "utils" --git

# JSON輸出
filepulse search "readme" --json

# 匯出結果
filepulse search "model" --export results.csv

📖 詳細使用指南

搜尋模式

# 📁 檔案名搜尋（預設）
filepulse search "app.py"

# 📝 內容搜尋（在檔案內容中查找）
filepulse search "import flask" --content

# 🎯 精確搜尋（禁用模糊匹配）
filepulse search "exact_name" --no-fuzzy

過濾與排序

# 按副檔名過濾
filepulse search "index" --type ts
filepulse search "component" --type-list "tsx,jsx,vue"

# 按大小過濾
filepulse search "log" --min-size 1KB --max-size 10MB

# 排序方式：frecency / name / size / modified / relevance
filepulse search "main" --sort size

TUI儀表板

# 啟動互動式儀表板
filepulse dashboard

# 指定目錄和重新整理間隔
filepulse dashboard --path /your/project --refresh 5

MCP Server（AI Agent整合）

# 啟動HTTP模式MCP Server
filepulse mcp --host 127.0.0.1 --port 8734

# 啟動stdio模式（用於直接Agent整合）
filepulse mcp --stdio

💡 設計思路與迭代規劃

設計理念： FilePulse-CLI的核心設計理念是「有記憶的搜尋」。傳統搜尋工具每次都從零開始，而FilePulse透過Frecency演算法學習使用者的使用模式——你經常存取的檔案會自動獲得更高的排名。這使得搜尋結果隨著使用越來越精準，特別適合在大型專案中日常使用。

後續迭代計劃：

• 增量檔案監聽（inotify/FSEvents）

• 正則表達式搜尋模式

• 檔案內容預覽功能

• 多倉庫聯合搜尋

• 搜尋歷史記錄與回溯

• Web UI儀表板

• 外掛系統（自訂搜尋後端）

📦 打包與部署指南

# 從原始碼安裝
git clone https://github.com/gitstq/FilePulse-CLI.git
cd FilePulse-CLI
pip install .

# 驗證安裝
filepulse --version

相容環境：

• Python 3.8, 3.9, 3.10, 3.11, 3.12

• Windows 10+, macOS 10.15+, Linux（主流發行版）

• 無需GPU、無需網路連線

🤝 貢獻指南

歡迎貢獻程式碼！請閱讀 CONTRIBUTING.md 了解詳情。

📄 開源協議

本專案基於 MIT License 開源。

🇺🇸 English

🎉 Introduction

FilePulse-CLI is a zero-dependency lightweight terminal intelligent file search engine. Inspired by the trending GitHub project fff, we built an independent pure-Python implementation with significant differentiating optimizations.

Core Pain Points Solved:

• 🔍 Every search starts from scratch — traditional tools (ripgrep/fzf) can't learn your usage patterns

• 🤖 AI Agents struggle with low search efficiency in large codebases, requiring multiple round trips

• 📁 Modified files in Git repositories can't be prioritized in search results

• 🌏 Poor support for CJK (Chinese/Japanese/Korean) file paths

Differentiating Features:

• 🧠 Frecency Ranking — Exponential decay algorithm combining frequency × recency, gets smarter with use

• 🎯 Fuzzy Matching with Tolerance — Subsequence matching + Levenshtein distance, type "mn" to find "main.py"

• 🔀 Git-Aware — Auto-detects modified/added files and boosts their ranking

• 🤖 MCP Server Mode — Native AI Agent integration (Claude Code/Cursor/Windsurf)

• 📊 TUI Interactive Dashboard — Real-time file distribution, Frecency rankings, Git status overview

• 🌏 CJK Path Optimization — Full fuzzy matching support for Chinese/Japanese/Korean characters

• 📤 Multi-Format Export — JSON / CSV / Markdown result export

• 🚫 Zero External Dependencies — Pure Python standard library, works out of the box

✨ Core Features

🚀 Quick Start

Requirements:

• Python 3.8 or higher

• No external dependencies needed

Installation:

# Option 1: Clone and run (recommended)
git clone https://github.com/gitstq/FilePulse-CLI.git
cd FilePulse-CLI
PYTHONPATH=src python -m filepulse --help

# Option 2: Install via pip
pip install .
filepulse --help

Basic Usage:

# Search by filename
filepulse search "main.py"

# Fuzzy search (enabled by default)
filepulse search "mn" --fuzzy

# Search file contents
filepulse search "def hello" --content

# Filter by file type
filepulse search "config" --type json

# Git-aware search (prioritize modified files)
filepulse search "utils" --git

# JSON output
filepulse search "readme" --json

# Export results
filepulse search "model" --export results.csv

📖 Detailed Usage Guide

Search Modes

# 📁 Filename search (default)
filepulse search "app.py"

# 📝 Content search (search within files)
filepulse search "import flask" --content

# 🎯 Exact search (disable fuzzy matching)
filepulse search "exact_name" --no-fuzzy

Filtering & Sorting

# Filter by extension
filepulse search "index" --type ts
filepulse search "component" --type-list "tsx,jsx,vue"

# Filter by size
filepulse search "log" --min-size 1KB --max-size 10MB

# Include hidden files
filepulse search "config" --hidden

# Sort by: frecency / name / size / modified / relevance
filepulse search "main" --sort size

TUI Dashboard

# Launch interactive dashboard
filepulse dashboard

# Specify directory and refresh interval
filepulse dashboard --path /your/project --refresh 5

MCP Server (AI Agent Integration)

# Start HTTP mode MCP Server
filepulse mcp --host 127.0.0.1 --port 8734

# Start stdio mode (for direct Agent integration)
filepulse mcp --stdio

Available MCP Tools:

• search_files — Search files by name with fuzzy matching

• search_content — Search file contents

• get_file_info — Get detailed file information

• list_directory — List directory contents

• get_frecency_stats — Get Frecency statistics

Frecency Statistics

# View search statistics
filepulse stats

# View top 20 files
filepulse stats --top 20

# JSON format output
filepulse stats --json

# Clear frecency data
filepulse stats --clear

💡 Design Philosophy & Roadmap

Design Philosophy: FilePulse-CLI's core design philosophy is "search with memory". Traditional search tools start from zero every time, while FilePulse learns your usage patterns through the Frecency algorithm — files you access frequently automatically rank higher. This makes search results increasingly accurate over time, especially useful for daily work in large projects.

Why These Tech Choices:

• Pure Python Standard Library — Zero-dependency strategy ensures it runs in any Python environment without version conflicts or network issues

• Frecency Algorithm — Inspired by Firefox's Frecency implementation, using exponential decay to balance frequency and recency

• MCP Protocol — JSON-RPC 2.0 standard ensures compatibility with mainstream AI Agents

Roadmap:

• Incremental file watching (inotify/FSEvents)

• Regex search mode

• File content preview

• Multi-repository search

• Search history & recall

• Web UI dashboard

• Plugin system (custom search backends)

📦 Packaging & Deployment

# Install from source
git clone https://github.com/gitstq/FilePulse-CLI.git
cd FilePulse-CLI
pip install .

# Verify installation
filepulse --version

Compatible Environments:

• Python 3.8, 3.9, 3.10, 3.11, 3.12

• Windows 10+, macOS 10.15+, Linux (major distributions)

• No GPU or network connection required

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

Quick Start:

1. Fork this repository

2. Create a feature branch (git checkout -b feature/your-feature)

3. Commit your changes (git commit -m 'feat: add your feature')

4. Push to the branch (git push origin feature/your-feature)

5. Open a Pull Request

📄 License

This project is licensed under the MIT License.

Made with 🦞 by FilePulse Team

灵感来源于 fff | Inspired by fff