Skip to content
Back to search

vfs

Reduce AI agent token usage by 98% via Virtual Function Signatures. MCP server for Cursor & Claude Desktop. Supports Go, TypeScript, Python, Rust, Java, Swift, Kotlin, C# and more.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/trngtien--vfs/badge.svg)](/listings/trngtien--vfs)

HTML

<a href="/listings/trngtien--vfs"><img src="/api/listings/trngtien--vfs/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Pre-built binary (Linux -- nothing else needed)

# x86_64
curl -L https://github.com/TrNgTien/vfs/releases/latest/download/vfs-linux-amd64.tar.gz | tar xz
sudo mv vfs /usr/local/bin/

# ARM64
curl -L https://github.com/TrNgTien/vfs/releases/latest/download/vfs-linux-arm64.tar.gz | tar xz
sudo mv vfs /usr/local/bin/

Build from source (macOS / Linux / Windows)

Requires **Go 1.24+** and a **C compiler** (tree-sitter C bindings):

| OS | Command | | --------------------- | --------------------------------------------------------------------------------------------------------------- | | macOS | `xcode-select --install` | | Linux (Debian/Ubuntu) | `sudo apt install build-essential` | | Linux (Fedora/RHEL) | `sudo yum groupinstall "Development Tools"` | | Windows | Install [TDM-GCC](https://jmeubank.github.io/tdm-gcc/) (easiest) or [MSYS2](https://www.msys2.org/) + MinGW-w64 |

git clone https://github.com/TrNgTien/vfs.git && cd vfs
go install ./cmd/vfs

> `vfs: command not found` after install? Add Go's bin to PATH: `export PATH="$PATH:$(go env GOPATH)/bin"` (macOS/Linux) or add `%USERPROFILE%\go\bin` to PATH (Windows).

Docker (any OS)

docker build -t vfs-mcp .
docker run --rm -v $(pwd):/workspace -p 8080:8080 -p 3000:3000 vfs-mcp

# Custom ports via environment variables
docker run --rm -v $(pwd):/workspace -e VFS_PORT=9090 -e VFS_DASHBOARD_PORT=4000 -p 9090:9090 -p 4000:4000 vfs-mcp

Verify Installation

vfs . -f HandleLogin   # Should show signatures, not an error
vfs bench --self       # Should show the savings table

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 391 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="static/vfs.png" alt="vfs logo" width="200" />
  3. </p>
  4. # vfs
  5. **Extract exported function signatures with bodies stripped -- cutting 60-70% of the tokens your AI agent reads on every code search.**
  6. [![CI](https://github.com/TrNgTien/vfs/actions/workflows/ci.yml/badge.svg)](https://github.com/TrNgTien/vfs/actions/workflows/ci.yml)
  7. [![Release](https://img.shields.io/github/v/release/TrNgTien/vfs)](https://github.com/TrNgTien/vfs/releases)
  8. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  9. [Install](#installation) • [Quick Start](#quick-start) • [Commands](#commands) • [Setup for AI Tools](#setup-for-ai-tools) • [Supported Languages](#supported-languages) • [Security & Privacy](#security--privacy)
  10. ---
  11. vfs parses source files via AST and tree-sitter and returns only exported signatures -- a compact "table of contents" of any codebase. One command (or one MCP call) replaces grep-and-read-everything with exact `file:line` pointers. Single Go binary, zero network access, works with any AI tool.
  12. ## What VFS Does
  13. | Instead of | vfs returns |
  14. | ------------------------------------------------ | ---------------------------------------------------------------------- |
  15. | `grep -r "HandleLogin" .` → 345 lines of matches | 21 signature lines |
  16. | Reading 7,979 lines to find one function | `auth.go:23: func HandleLogin(w http.ResponseWriter, r *http.Request)` |
  17. | ~48,757 tokens of context | ~570 tokens |
  18. ## How Savings Work
  19. vfs measures **bytes of source that reach the model**, estimated as `bytes / 4`. Bodies are stripped at parse time, so a function that costs 50 lines of context costs one line. The savings are real but the absolute token numbers are approximate -- vfs ships no tokenizer.
  20. On this repository (`vfs bench --self`, pattern `"Extract"`):
  21. | | Read all files | grep | vfs |
  22. | ----------- | -------------- | ------- | ------ |
  23. | Output size | 190.5 KB | 47.5 KB | 2.2 KB |
  24. | Lines | 7,979 | 345 | 21 |
  25. | Est. tokens | 48,757 | 12,154 | 570 |
  26. - **98.8% fewer tokens** vs reading all files (48,757 → 570)
  27. - **95.3% fewer tokens** vs grep (12,154 → 570)
  28. > These are reductions in context tokens, not in your bill -- but for a tool your agent runs on every search, they add up fast.
  29. ## Installation
  30. ### Pre-built binary (Linux -- nothing else needed)
  31. ```bash
  32. # x86_64
  33. curl -L https://github.com/TrNgTien/vfs/releases/latest/download/vfs-linux-amd64.tar.gz | tar xz
  34. sudo mv vfs /usr/local/bin/
  35. # ARM64
  36. curl -L https://github.com/TrNgTien/vfs/releases/latest/download/vfs-linux-arm64.tar.gz | tar xz
  37. sudo mv vfs /usr/local/bin/
  38. ```
  39. ### Build from source (macOS / Linux / Windows)
  40. Requires **Go 1.24+** and a **C compiler** (tree-sitter C bindings):
  41. | OS | Command |
  42. | --------------------- | --------------------------------------------------------------------------------------------------------------- |
  43. | macOS | `xcode-select --install` |
  44. | Linux (Debian/Ubuntu) | `sudo apt install build-essential` |
  45. | Linux (Fedora/RHEL) | `sudo yum groupinstall "Development Tools"` |
  46. | Windows | Install [TDM-GCC](https://jmeubank.github.io/tdm-gcc/) (easiest) or [MSYS2](https://www.msys2.org/) + MinGW-w64 |
  47. ```bash
  48. git clone https://github.com/TrNgTien/vfs.git && cd vfs
  49. go install ./cmd/vfs
  50. ```
  51. > `vfs: command not found` after install? Add Go's bin to PATH: `export PATH="$PATH:$(go env GOPATH)/bin"` (macOS/Linux) or add `%USERPROFILE%\go\bin` to PATH (Windows).
  52. ### Docker (any OS)
  53. ```bash
  54. docker build -t vfs-mcp .
  55. docker run --rm -v $(pwd):/workspace -p 8080:8080 -p 3000:3000 vfs-mcp
  56. # Custom ports via environment variables
  57. docker run --rm -v $(pwd):/workspace -e VFS_PORT=9090 -e VFS_DASHBOARD_PORT=4000 -p 9090:9090 -p 4000:4000 vfs-mcp
  58. ```
  59. ### Verify Installation
  60. ```bash
  61. vfs . -f HandleLogin # Should show signatures, not an error
  62. vfs bench --self # Should show the savings table
  63. ```
  64. ## Quick Start
  65. ```bash
  66. # Find a function by name (case-insensitive)
  67. vfs . -f HandleLogin
  68. # List all signatures in a directory or file
  69. vfs ./internal ./pkg
  70. vfs server.go
  71. # Show token savings after output
  72. vfs . -f auth --stats
  73. # Start the MCP server + dashboard (detached)
  74. vfs up
  75. # Check / stop it
  76. vfs status
  77. vfs down
  78. ```
  79. Then open the dashboard at `http://localhost:3000` for usage stats over time.
  80. ## How It Works
  81. ```
  82. Without vfs: With vfs:
  83. Agent --grep "HandleLogin"--> shell Agent --vfs search--> vfs (AST)
  84. ^ | ^ |
  85. | 345 lines of matches | | 2 sigs, ~570 tokens |
  86. +--------------------------------+ +--- file:line + signature -+
  87. ```
  88. Four properties make the savings work:
  89. 1. **AST parsing** - understands structure, not just text. Finds `class User`, `type User struct`, `func (u *User) Login`, not just string matches.
  90. 2. **Bodies stripped** - you get the signature, not the 50 lines underneath it.
  91. 3. **Case-insensitive filter** - one search finds `fare`, `Fare`, and `FARE`.
  92. 4. **Token accounting** - every invocation is measured and reported (`--stats`, `vfs stats`, dashboard).
  93. The companion rule in this repo ([`.cursor/rules/vfs-agent-search.mdc`](.cursor/rules/vfs-agent-search.mdc)) teaches agents when to use vfs (locate/understand/modify) vs grep (debug, string literals, callers) -- see [Setup for AI Tools](#setup-for-ai-tools).
  94. ## Commands
  95. ### Search
  96. ```bash
  97. vfs . # All exported signatures (recursive)
  98. vfs ./src ./lib # Multiple directories
  99. vfs handler.go # Single file
  100. vfs . -f auth # Case-insensitive filter
  101. vfs . -f auth --stats # + token savings report
  102. vfs . -f auth --no-record # Skip history logging
  103. ```
  104. ### Benchmarks
  105. ```bash
  106. vfs bench --self # Self-test on vfs source
  107. vfs bench -f HandleLogin /path/to/project # Benchmark any project
  108. vfs bench -f Login /path --show-output # Show actual grep/vfs output
  109. ```
  110. ### Statistics
  111. ```bash
  112. vfs stats # Lifetime token savings
  113. vfs stats --json # JSON export for dashboards/CI
  114. vfs stats --reset # Clear all history
  115. ```
  116. ### MCP Server
  117. ```bash
  118. vfs mcp # stdio transport (default, editor integration)
  119. vfs mcp --http :8080 # HTTP transport (Docker / remote)
  120. vfs serve # MCP + dashboard, foreground
  121. vfs serve --port 9090 --dashboard-port 4000 # custom ports
  122. vfs up # Same, detached (background)
  123. vfs status # Is it running? show endpoints
  124. vfs down # Stop the detached server
  125. vfs dashboard # Dashboard UI only
  126. ```
  127. MCP tools exposed: `search`, `extract`, `list_languages`.
  128. ## Global Flags
  129. | Flag | Description |
  130. | ---------------- | ------------------------------------------------------ |
  131. | `-f`, `--filter` | Case-insensitive substring filter on signature names |
  132. | `--stats` | Print token savings (raw vs vfs) to stderr |
  133. | `--no-record` | Skip logging this invocation to `~/.vfs/history.jsonl` |
  134. | `--version` | Show version, commit, and build date |
  135. ## Examples
  136. **"Where is the login handler?"**
  137. ```
  138. # Without vfs: grep + read
  139. grep -r "HandleLogin" . # 345 lines of matches
  140. cat auth.go # then read the whole file
  141. # With vfs
  142. vfs . -f login
  143. → internal/handlers/auth.go:23: func HandleLogin(w http.ResponseWriter, r *http.Request)
  144. → internal/services/auth.go:10: func ValidateToken(token string) (*Claims, error)
  145. → internal/middleware/jwt.go:45: func RequireLogin(next http.Handler) http.Handler
  146. ```
  147. **Multi-language project:**
  148. ```
  149. vfs . -f user
  150. → internal/services/user.go:42: func CreateUser(name string, email string) (*User, error)
  151. → src/hooks/useUser.ts:8: export function useUser(id: string): UserState
  152. → app/models/user.py:15: class User(BaseModel)
  153. → src/api/UserService.java:22: public class UserService
  154. → contracts/UserRegistry.sol:10: contract UserRegistry is Ownable { ... }
  155. ```
  156. **When grep IS the right tool** -- vfs finds definitions, not bodies, callers, or config keys:
  157. ```
  158. grep "INVALID_API_KEY" ./internal/ # string literal inside a function body
  159. grep "database_url" ./*.yaml # non-code file
  160. grep "CalculateFare" ./internal/ # who CALLS it (vfs finds the definition)
  161. ```
  162. ## Setup for AI Tools
  163. Two steps -- both required:
  164. 1. **Connect vfs** -- make it reachable from the agent (MCP preferred, CLI fallback).
  165. 2. **Add an agent rule** -- tell the agent it *should* call vfs before grep. Without the rule, the agent ignores vfs even when installed.
  166. ### Step 1: Connect vfs
  167. | Method | How it works | Best for |
  168. | --------------------- | ------------------------------------------------------------ | ---------------------------------------------------- |
  169. | **MCP (recommended)** | Agent calls `search` / `extract` / `list_languages` directly | Editors with MCP support (most modern AI tools) |
  170. | **CLI** | Agent runs `vfs <path> -f <pattern>` via shell | Terminal tools, scripts, sandboxed-free environments |
  171. **Stdio config** (Cursor, Claude Code, Claude Desktop, Antigravity, Windsurf, Cline):
  172. ```json
  173. {
  174. "mcpServers": {
  175. "vfs": {
  176. "command": "vfs",
  177. "args": ["mcp"]
  178. }
  179. }
  180. }
  181. ```
  182. **Claude Code** (preferred): `claude mcp add vfs -- vfs mcp` -- registers in `~/.claude.json`.
  183. **Continue**:
  184. ```json
  185. {
  186. "experimental": {
  187. "modelContextProtocolServers": [
  188. { "transport": { "type": "stdio", "command": "vfs", "args": ["mcp"] } }
  189. ]
  190. }
  191. }
  192. ```
  193. **Zed**:
  194. ```json
  195. {
  196. "context_servers": {
  197. "vfs": { "command": { "path": "vfs", "args": ["mcp"] } }
  198. }
  199. }
  200. ```
  201. **HTTP config** (Docker, remote, or tools that prefer HTTP):
  202. ```bash
  203. vfs up # MCP on :8080, dashboard on :3000
  204. vfs up --port 9090
  205. ```
  206. ```json
  207. {
  208. "mcpServers": { "vfs": { "url": "http://localhost:8080/mcp" } }
  209. }
  210. ```
  211. ### Step 2: Add an agent rule (required)
  212. Installing vfs is not enough -- agents don't know it exists. This repo ships a production-ready rule at [`.cursor/rules/vfs-agent-search.mdc`](.cursor/rules/vfs-agent-search.mdc), and a one-command installer to put it into your tool:
  213. ```bash
  214. ./scripts/install-rules.sh # auto-detect your AI tool
  215. ./scripts/install-rules.sh --agent cursor # install for one tool
  216. ./scripts/install-rules.sh --agent all # every tool
  217. ./scripts/install-rules.sh --project ../myapp --agent claude # another project
  218. ./scripts/install-rules.sh --list # supported tools + paths
  219. ```
  220. Same via Make: `make rules` or `make rules RULES_ARGS="--agent windsurf --project ../myapp"`.
  221. The installer is idempotent and safe: plain-markdown tools (Claude Code, Cline, Aider, Antigravity) get the rule **appended** under a `## vfs:` heading -- your existing config is never overwritten -- while frontmatter tools (Cursor, Windsurf, Continue, OpenCode) get a verbatim copy.
  222. | Tool | Rule file | Notes |
  223. | -------------------- | ------------------------- | ------------------------------------------------------ |
  224. | **Cursor** | `.cursor/rules/vfs.mdc` | Copy of `.mdc` (frontmatter kept) |
  225. | **Claude Code** | `CLAUDE.md` | Appended, frontmatter stripped |
  226. | **Antigravity** | `GEMINI.md` | Appended, frontmatter stripped; also reads `AGENTS.md` |
  227. | **Windsurf** | `.windsurf/rules/vfs.md` | Copy of `.mdc` |
  228. | **Cline / Roo Code** | `.clinerules` | Appended, frontmatter stripped |
  229. | **Continue** | `.continue/rules/vfs.md` | Copy of `.mdc` |
  230. | **Aider** | `.aider.conventions.md` | Appended, frontmatter stripped |
  231. | **OpenCode** | `.opencode/rules/vfs.mdc` | Copy of `.mdc` |
  232. Without the rule, this is what happens:
  233. ```
  234. You: "Where is the login handler?"
  235. ❌ No rule: Agent greps + reads → 345 lines → 12,000+ tokens
  236. ✅ With rule: Agent calls vfs → reads 23 lines → ~570 tokens
  237. ```
  238. ## Supported Languages
  239. | Language | Extensions | Parser |
  240. | --------------- | ----------------------------- | ----------- |
  241. | Go | `.go` | `go/ast` |
  242. | JavaScript | `.js`, `.mjs`, `.cjs`, `.jsx` | tree-sitter |
  243. | TypeScript | `.ts`, `.mts`, `.cts`, `.tsx` | tree-sitter |
  244. | Python | `.py` | tree-sitter |
  245. | Rust | `.rs` | tree-sitter |
  246. | Java | `.java` | tree-sitter |
  247. | C# | `.cs` | tree-sitter |
  248. | Dart | `.dart` | tree-sitter |
  249. | Kotlin | `.kt`, `.kts` | tree-sitter |
  250. | Swift | `.swift` | tree-sitter |
  251. | Ruby | `.rb` | tree-sitter |
  252. | Solidity | `.sol` | tree-sitter |
  253. | HCL / Terraform | `.tf`, `.hcl` | tree-sitter |
  254. | Dockerfile | `Dockerfile`, `Dockerfile.*` | line-based |
  255. | Protobuf | `.proto` | line-based |
  256. | SQL | `.sql` | line-based |
  257. | YAML | `.yml`, `.yaml` | line-based |
  258. ## Security & Privacy
  259. vfs is local-only and offline.
  260. | Property | Detail |
  261. | ------------------- | -------------------------------------------------------------------------------------------------- |
  262. | Zero network access | All parsing is local. No outbound connections, ever |
  263. | No secrets exposure | Does not read or store API keys, credentials, or environment variables |
  264. | No data collection | No telemetry, no analytics, no tracking |
  265. | No code storage | Source is parsed in memory and discarded. Only `~/.vfs/history.jsonl` (scan statistics) is written |
  266. ## Configuration
  267. There is no config file -- vfs is zero-config. The only state it keeps is scan history for stats and the dashboard:
  268. | File | Purpose |
  269. | ---------------------- | ------------------------------------------------------------- |
  270. | `~/.vfs/history.jsonl` | One line per invocation (paths, filter, bytes, tokens saved) |
  271. | `~/.vfs/vfs.state` | Running server PID + endpoints (used by `up`/`down`/`status`) |
  272. Clear it anytime with `vfs stats --reset`.
  273. ## Contributing
  274. Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. When you add a language, update the supported-languages tables in `AGENTS.md` and `README.md`.
  275. Releases are automated via [`.github/workflows/release.yml`](.github/workflows/release.yml) -- see [`scripts/release.sh`](scripts/release.sh).
  276. ## Used By
  277. > Using vfs in your project or company? [Submit a PR](#how-to-add-your-use-case) to be listed here.
  278. | Logo | Name | Website | Use Case | Blog |
  279. | :---------: | :----------------------- | :---------- | :----------------------- | :------- |
  280. | *(img url)* | *(Company/Project Name)* | [Website]() | *(Use Case Description)* | [Read]() |
  281. ### How to Add Your Use Case
  282. 1. Fork this repo and create a branch: `usecase/<your-company-or-project>`
  283. 2. Add one row to the table above (logo, name, website, one-line use case, optional blog).
  284. 3. Open a pull request titled `usecase: add <Company/Project>`.
  285. No proprietary details needed -- a high-level description is fine.
  286. ## License
  287. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.