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.
Badge for your README
Markdown
[](/listings/trngtien--vfs)HTML
<a href="/listings/trngtien--vfs"><img src="/api/listings/trngtien--vfs/badge.svg" alt="findsafeskills safety rating" /></a>Install
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)
- <p align="center">
- <img src="static/vfs.png" alt="vfs logo" width="200" />
- </p>
- # vfs
- **Extract exported function signatures with bodies stripped -- cutting 60-70% of the tokens your AI agent reads on every code search.**
- [](https://github.com/TrNgTien/vfs/actions/workflows/ci.yml)
- [](https://github.com/TrNgTien/vfs/releases)
- [](LICENSE)
- [Install](#installation) • [Quick Start](#quick-start) • [Commands](#commands) • [Setup for AI Tools](#setup-for-ai-tools) • [Supported Languages](#supported-languages) • [Security & Privacy](#security--privacy)
- ---
- 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.
- ## What VFS Does
- | Instead of | vfs returns |
- | ------------------------------------------------ | ---------------------------------------------------------------------- |
- | `grep -r "HandleLogin" .` → 345 lines of matches | 21 signature lines |
- | Reading 7,979 lines to find one function | `auth.go:23: func HandleLogin(w http.ResponseWriter, r *http.Request)` |
- | ~48,757 tokens of context | ~570 tokens |
- ## How Savings Work
- 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.
- On this repository (`vfs bench --self`, pattern `"Extract"`):
- | | Read all files | grep | vfs |
- | ----------- | -------------- | ------- | ------ |
- | Output size | 190.5 KB | 47.5 KB | 2.2 KB |
- | Lines | 7,979 | 345 | 21 |
- | Est. tokens | 48,757 | 12,154 | 570 |
- - **98.8% fewer tokens** vs reading all files (48,757 → 570)
- - **95.3% fewer tokens** vs grep (12,154 → 570)
- > These are reductions in context tokens, not in your bill -- but for a tool your agent runs on every search, they add up fast.
- ## Installation
- ### Pre-built binary (Linux -- nothing else needed)
- ```bash
- # 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 |
- ```bash
- 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)
- ```bash
- 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
- ```bash
- vfs . -f HandleLogin # Should show signatures, not an error
- vfs bench --self # Should show the savings table
- ```
- ## Quick Start
- ```bash
- # Find a function by name (case-insensitive)
- vfs . -f HandleLogin
- # List all signatures in a directory or file
- vfs ./internal ./pkg
- vfs server.go
- # Show token savings after output
- vfs . -f auth --stats
- # Start the MCP server + dashboard (detached)
- vfs up
- # Check / stop it
- vfs status
- vfs down
- ```
- Then open the dashboard at `http://localhost:3000` for usage stats over time.
- ## How It Works
- ```
- Without vfs: With vfs:
- Agent --grep "HandleLogin"--> shell Agent --vfs search--> vfs (AST)
- ^ | ^ |
- | 345 lines of matches | | 2 sigs, ~570 tokens |
- +--------------------------------+ +--- file:line + signature -+
- ```
- Four properties make the savings work:
- 1. **AST parsing** - understands structure, not just text. Finds `class User`, `type User struct`, `func (u *User) Login`, not just string matches.
- 2. **Bodies stripped** - you get the signature, not the 50 lines underneath it.
- 3. **Case-insensitive filter** - one search finds `fare`, `Fare`, and `FARE`.
- 4. **Token accounting** - every invocation is measured and reported (`--stats`, `vfs stats`, dashboard).
- 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).
- ## Commands
- ### Search
- ```bash
- vfs . # All exported signatures (recursive)
- vfs ./src ./lib # Multiple directories
- vfs handler.go # Single file
- vfs . -f auth # Case-insensitive filter
- vfs . -f auth --stats # + token savings report
- vfs . -f auth --no-record # Skip history logging
- ```
- ### Benchmarks
- ```bash
- vfs bench --self # Self-test on vfs source
- vfs bench -f HandleLogin /path/to/project # Benchmark any project
- vfs bench -f Login /path --show-output # Show actual grep/vfs output
- ```
- ### Statistics
- ```bash
- vfs stats # Lifetime token savings
- vfs stats --json # JSON export for dashboards/CI
- vfs stats --reset # Clear all history
- ```
- ### MCP Server
- ```bash
- vfs mcp # stdio transport (default, editor integration)
- vfs mcp --http :8080 # HTTP transport (Docker / remote)
- vfs serve # MCP + dashboard, foreground
- vfs serve --port 9090 --dashboard-port 4000 # custom ports
- vfs up # Same, detached (background)
- vfs status # Is it running? show endpoints
- vfs down # Stop the detached server
- vfs dashboard # Dashboard UI only
- ```
- MCP tools exposed: `search`, `extract`, `list_languages`.
- ## Global Flags
- | Flag | Description |
- | ---------------- | ------------------------------------------------------ |
- | `-f`, `--filter` | Case-insensitive substring filter on signature names |
- | `--stats` | Print token savings (raw vs vfs) to stderr |
- | `--no-record` | Skip logging this invocation to `~/.vfs/history.jsonl` |
- | `--version` | Show version, commit, and build date |
- ## Examples
- **"Where is the login handler?"**
- ```
- # Without vfs: grep + read
- grep -r "HandleLogin" . # 345 lines of matches
- cat auth.go # then read the whole file
- # With vfs
- vfs . -f login
- → internal/handlers/auth.go:23: func HandleLogin(w http.ResponseWriter, r *http.Request)
- → internal/services/auth.go:10: func ValidateToken(token string) (*Claims, error)
- → internal/middleware/jwt.go:45: func RequireLogin(next http.Handler) http.Handler
- ```
- **Multi-language project:**
- ```
- vfs . -f user
- → internal/services/user.go:42: func CreateUser(name string, email string) (*User, error)
- → src/hooks/useUser.ts:8: export function useUser(id: string): UserState
- → app/models/user.py:15: class User(BaseModel)
- → src/api/UserService.java:22: public class UserService
- → contracts/UserRegistry.sol:10: contract UserRegistry is Ownable { ... }
- ```
- **When grep IS the right tool** -- vfs finds definitions, not bodies, callers, or config keys:
- ```
- grep "INVALID_API_KEY" ./internal/ # string literal inside a function body
- grep "database_url" ./*.yaml # non-code file
- grep "CalculateFare" ./internal/ # who CALLS it (vfs finds the definition)
- ```
- ## Setup for AI Tools
- Two steps -- both required:
- 1. **Connect vfs** -- make it reachable from the agent (MCP preferred, CLI fallback).
- 2. **Add an agent rule** -- tell the agent it *should* call vfs before grep. Without the rule, the agent ignores vfs even when installed.
- ### Step 1: Connect vfs
- | Method | How it works | Best for |
- | --------------------- | ------------------------------------------------------------ | ---------------------------------------------------- |
- | **MCP (recommended)** | Agent calls `search` / `extract` / `list_languages` directly | Editors with MCP support (most modern AI tools) |
- | **CLI** | Agent runs `vfs <path> -f <pattern>` via shell | Terminal tools, scripts, sandboxed-free environments |
- **Stdio config** (Cursor, Claude Code, Claude Desktop, Antigravity, Windsurf, Cline):
- ```json
- {
- "mcpServers": {
- "vfs": {
- "command": "vfs",
- "args": ["mcp"]
- }
- }
- }
- ```
- **Claude Code** (preferred): `claude mcp add vfs -- vfs mcp` -- registers in `~/.claude.json`.
- **Continue**:
- ```json
- {
- "experimental": {
- "modelContextProtocolServers": [
- { "transport": { "type": "stdio", "command": "vfs", "args": ["mcp"] } }
- ]
- }
- }
- ```
- **Zed**:
- ```json
- {
- "context_servers": {
- "vfs": { "command": { "path": "vfs", "args": ["mcp"] } }
- }
- }
- ```
- **HTTP config** (Docker, remote, or tools that prefer HTTP):
- ```bash
- vfs up # MCP on :8080, dashboard on :3000
- vfs up --port 9090
- ```
- ```json
- {
- "mcpServers": { "vfs": { "url": "http://localhost:8080/mcp" } }
- }
- ```
- ### Step 2: Add an agent rule (required)
- 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:
- ```bash
- ./scripts/install-rules.sh # auto-detect your AI tool
- ./scripts/install-rules.sh --agent cursor # install for one tool
- ./scripts/install-rules.sh --agent all # every tool
- ./scripts/install-rules.sh --project ../myapp --agent claude # another project
- ./scripts/install-rules.sh --list # supported tools + paths
- ```
- Same via Make: `make rules` or `make rules RULES_ARGS="--agent windsurf --project ../myapp"`.
- 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.
- | Tool | Rule file | Notes |
- | -------------------- | ------------------------- | ------------------------------------------------------ |
- | **Cursor** | `.cursor/rules/vfs.mdc` | Copy of `.mdc` (frontmatter kept) |
- | **Claude Code** | `CLAUDE.md` | Appended, frontmatter stripped |
- | **Antigravity** | `GEMINI.md` | Appended, frontmatter stripped; also reads `AGENTS.md` |
- | **Windsurf** | `.windsurf/rules/vfs.md` | Copy of `.mdc` |
- | **Cline / Roo Code** | `.clinerules` | Appended, frontmatter stripped |
- | **Continue** | `.continue/rules/vfs.md` | Copy of `.mdc` |
- | **Aider** | `.aider.conventions.md` | Appended, frontmatter stripped |
- | **OpenCode** | `.opencode/rules/vfs.mdc` | Copy of `.mdc` |
- Without the rule, this is what happens:
- ```
- You: "Where is the login handler?"
- ❌ No rule: Agent greps + reads → 345 lines → 12,000+ tokens
- ✅ With rule: Agent calls vfs → reads 23 lines → ~570 tokens
- ```
- ## Supported Languages
- | Language | Extensions | Parser |
- | --------------- | ----------------------------- | ----------- |
- | Go | `.go` | `go/ast` |
- | JavaScript | `.js`, `.mjs`, `.cjs`, `.jsx` | tree-sitter |
- | TypeScript | `.ts`, `.mts`, `.cts`, `.tsx` | tree-sitter |
- | Python | `.py` | tree-sitter |
- | Rust | `.rs` | tree-sitter |
- | Java | `.java` | tree-sitter |
- | C# | `.cs` | tree-sitter |
- | Dart | `.dart` | tree-sitter |
- | Kotlin | `.kt`, `.kts` | tree-sitter |
- | Swift | `.swift` | tree-sitter |
- | Ruby | `.rb` | tree-sitter |
- | Solidity | `.sol` | tree-sitter |
- | HCL / Terraform | `.tf`, `.hcl` | tree-sitter |
- | Dockerfile | `Dockerfile`, `Dockerfile.*` | line-based |
- | Protobuf | `.proto` | line-based |
- | SQL | `.sql` | line-based |
- | YAML | `.yml`, `.yaml` | line-based |
- ## Security & Privacy
- vfs is local-only and offline.
- | Property | Detail |
- | ------------------- | -------------------------------------------------------------------------------------------------- |
- | Zero network access | All parsing is local. No outbound connections, ever |
- | No secrets exposure | Does not read or store API keys, credentials, or environment variables |
- | No data collection | No telemetry, no analytics, no tracking |
- | No code storage | Source is parsed in memory and discarded. Only `~/.vfs/history.jsonl` (scan statistics) is written |
- ## Configuration
- There is no config file -- vfs is zero-config. The only state it keeps is scan history for stats and the dashboard:
- | File | Purpose |
- | ---------------------- | ------------------------------------------------------------- |
- | `~/.vfs/history.jsonl` | One line per invocation (paths, filter, bytes, tokens saved) |
- | `~/.vfs/vfs.state` | Running server PID + endpoints (used by `up`/`down`/`status`) |
- Clear it anytime with `vfs stats --reset`.
- ## Contributing
- 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`.
- Releases are automated via [`.github/workflows/release.yml`](.github/workflows/release.yml) -- see [`scripts/release.sh`](scripts/release.sh).
- ## Used By
- > Using vfs in your project or company? [Submit a PR](#how-to-add-your-use-case) to be listed here.
- | Logo | Name | Website | Use Case | Blog |
- | :---------: | :----------------------- | :---------- | :----------------------- | :------- |
- | *(img url)* | *(Company/Project Name)* | [Website]() | *(Use Case Description)* | [Read]() |
- ### How to Add Your Use Case
- 1. Fork this repo and create a branch: `usecase/<your-company-or-project>`
- 2. Add one row to the table above (logo, name, website, one-line use case, optional blog).
- 3. Open a pull request titled `usecase: add <Company/Project>`.
- No proprietary details needed -- a high-level description is fine.
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.