Start here

file.cheap gives files produced during agent work a durable local lifecycle. It can snapshot an arbitrary file or folder, record where it came from, search its contents later, and restore the exact saved bytes with hash verification.

The vault is local by default. You do not need an account or hosted service to save, list, search, or restore a stash.

Choose a path

Goal	Start with
Install file.cheap and save something useful	Getting started
Understand manifests, indexes, and the local storage model	Core concepts
Follow complete CLI and agent workflows	Workflow examples
Give an AI assistant safe operating instructions	Agent guide
Connect Claude Code, Codex CLI, or another MCP client	MCP client setup
Diagnose an installation or operation	Troubleshooting
Look up a command or global flag	CLI reference

The core loop

Most workflows use the same sequence:

save -> index -> search or inspect -> restore when needed -> retain or remove

You can combine the first two steps with fcheap save --index. A successful save returns an opaque stash ID. Keep that ID in an issue, agent transcript, or investigation note so another operation can address the same snapshot.

fcheap save ./evidence --tag bug-123 --tool manual --index
fcheap search "checkout stopped"
fcheap info <stash-id>
fcheap restore <stash-id>

Search returns matching saved files and snippets. Restore without --to creates a fresh temporary directory and verifies the restored files against the manifest.

What ships today

file.cheap is a local-first CLI, MCP server, and terminal UI. The installed Go binary includes:

• file and folder snapshots with provenance and tags;
• save-time secret scanning;
• streaming compression and verified restore;
• local BM25 search, with optional semantic and hybrid search;
• comparison against a corresponding live directory;
• optional vecgrep integration for connecting evidence to likely source code;
• retention, cleanup planning, and a Studio terminal interface;
• embedded documentation and an operating guide for agents.

It does not currently provide cloud sync, accounts, an HTTP API, authentication, or billing. Optional OpenAI and non-loopback Ollama embedders can receive text when you explicitly configure them; the stash payload itself remains in the local vault.

Next step

Follow Getting started for an executable first stash, search, and verified restore.