<p align="center"> <img src="static/vfs.png" alt="vfs logo" width="200" /> </p>

vfs

Virtual Function Signatures -- extract exported function, class, interface, and type signatures from source code with bodies stripped.

Why vfs?

AI coding agents waste tokens by grepping or reading entire files just to find a function. vfs parses source via AST and tree-sitter, returning only the signatures -- a compact "table of contents" of any codebase.

60-70% fewer tokens per search.

It works with any AI coding tool -- Cursor, Claude Code, Antigravity, Windsurf, Cline, Continue, Aider, Copilot, Zed, or your own scripts. No vendor lock-in.

How It Works

flowchart TD
    A["Agent classifies intent"] --> B{"Intent?"}

    B -->|Locate| C["vfs search"]
    B -->|Understand| C
    B -->|Modify| C
    B -->|Debug| D["Grep / Read"]

    C --> E["file:line + signature\n~370 tokens"]
    E --> F{"Need behavior\nor just location?"}

    F -->|"Location only"| Done["Done"]
    F -->|"Need behavior"| G["Read exact lines\n(body + imports)"]

    G --> H{"Modifying?"}
    H -->|Yes| I["Grep for callers"]
    H -->|No| Done

    I --> Done
    D --> Done

The agent classifies its intent first. For Locate, Understand, and Modify intents, vfs runs first to get signatures (~370 tokens vs ~26,000 for reading files). Only then does the agent Read exact lines or Grep for callers as needed. For Debug intent, Grep goes first since you need to search inside function bodies.

Given a Go project with thousands of lines, asking "where is the login handler?" traditionally means grepping or reading entire files. vfs gives you just the signatures:

$ 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

Each line tells you the file, line number, and full signature -- no function bodies, no imports, no noise. You (or your AI agent) can then read only the exact lines needed.

This works across 17 languages:

$ vfs ./frontend -f auth
src/hooks/useAuth.ts:5:         export function useAuth(): AuthContext
src/components/LoginForm.tsx:12: export const LoginForm: React.FC<LoginFormProps>
src/api/client.py:28:           def authenticate(username: str, password: str) -> Token

Benchmark

Self-benchmark on this repository (pattern "Extract", 4,178 lines of source):

| | Read all files | grep | vfs | |-----------------|----------------|------------|------------| | Output size | 101.9 KB | 13.8 KB | 1.5 KB | | Lines | 4,178 | 148 | 15 | | Est. tokens | 26,079 | 3,537 | 373 |

• vfs saves 98.6% tokens vs reading all files (26,079 -> 373)
• vfs saves 89.5% tokens vs grep (3,537 -> 373)

Run it yourself:

vfs bench --self                                   # self-test on vfs source
vfs bench -f HandleLogin /path/to/go-project       # benchmark on any project
vfs bench -f Login /path/to/project --show-output  # show actual output

Security & Privacy

Local-first by design. Your source code never leaves your machine.

• Zero network access -- all parsing is local via AST and tree-sitter. No outbound connections, ever.
• No secrets exposure -- does not read, access, 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.
• Fully offline -- install once, use forever.

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 |

Install

| Your situation | Method | What you need | |---|---|---| | Linux | Pre-built binary | Nothing | | macOS / Linux / Windows | Build from source | Go 1.24+, C compiler | | Any OS | Docker | Docker |

Pre-built binary

Download from GitHub Releases. No Go, no C compiler needed. Each release includes SHA-256 checksums.

# Linux 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/

# Linux 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

Requires Go 1.24+ and a C compiler:

• macOS: xcode-select --install
• Linux: sudo apt install build-essential (Debian/Ubuntu) or sudo yum groupinstall "Development Tools" (Fedora/RHEL)
• Windows: install TDM-GCC (easiest) or MSYS2 + MinGW-w64

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

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

Docker

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

Quick Start

# Find a function by name (case-insensitive)
vfs . -f HandleLogin

# Scan specific directories
vfs ./internal ./pkg

# List all signatures in a single file
vfs server.go

# Show token savings stats after output
vfs . -f auth --stats

# Start the MCP server + dashboard in the background
vfs up

# Start on a custom port (default: 8080)
vfs up --port 9090

# Check server status
vfs status

# Stop the server
vfs down

Open the dashboard at http://localhost:3000 to see usage statistics and token savings over time.

Run vfs --help for all commands and flags.

CLI Reference

vfs [paths...] -f <pattern>

The main command. Scans files/directories and prints exported signatures.

vfs .                          # all signatures in current directory (recursive)
vfs ./src ./lib                # scan multiple directories
vfs handler.go                 # single file
vfs . -f auth                  # filter by pattern (case-insensitive)
vfs . -f auth --stats          # show token efficiency stats after output
vfs . -f auth --no-record      # skip logging to history

Flags:

| Flag | Description | |------|-------------| | -f, --filter | Case-insensitive substring filter on signature names | | --stats | Print token efficiency stats (raw vs vfs) to stderr | | --no-record | Skip logging this invocation to ~/.vfs/history.jsonl |

vfs bench

Compare token usage: reading all files vs grep vs vfs.

vfs bench --self                              # benchmark on vfs's own source
vfs bench -f HandleLogin /path/to/project     # benchmark on any project
vfs bench -f Login /path/to/project --show-output  # also print actual output

vfs stats

Show lifetime token savings across all recorded invocations.

vfs stats            # show summary
vfs stats --reset    # clear all history

Example output:

--- vfs lifetime stats ---
Invocations:         142
Total tokens saved:  ~52,300
Total raw scanned:   2.3 MB  (48,200 lines)
Total vfs output:    89.5 KB  (1,420 lines)
Avg reduction:       72.3%
First recorded:      2025-01-15 09:30
Last recorded:       2025-03-09 14:22

vfs mcp

Start the MCP server for AI tool integration.

vfs mcp                  # stdio transport (default, for editor integration)
vfs mcp --http :8080     # HTTP transport (for Docker / remote setups)

vfs serve

Run the MCP server (HTTP) and dashboard together in the foreground.

vfs serve                                    # defaults: MCP on :8080, dashboard on :3000
vfs serve --port 9090                        # MCP on :9090
vfs serve --port 9090 --dashboard-port 4000  # both custom
vfs serve --mcp :9090 --dashboard-port 4000  # equivalent (full address form)

vfs up / vfs down / vfs status

Manage the server as a background process.

vfs up                  # start MCP + dashboard in background (default port 8080)
vfs up --port 9090      # start on custom MCP port
vfs status              # check if running, show endpoints
vfs status --port 9