Folderbase documentation

Folderbase turns an ordinary folder into a structured, versioned workspace that humans and agents can understand across sessions. Your files remain normal files. A small .folderbase/ directory adds durable identity, protocol records, history, and policy.

Start here

Install Folderbase

Choose npx, a native release binary, or Cargo.

Five-minute quickstart

Inspect, preview, initialize, and validate a folder.

Migrate a mixed folder

Generate a reviewable organization plan without applying it.

Operate from an agent

List, read, and save files with explicit concurrency control.

What Core 0.5 guarantees

A stable discoverable CLI JSON contract.
A compatibility contract for portable records and extension preservation.
Review-first initialization and migration workflows.
Local-first operation without a Folderbase account.
Native binaries for macOS and Linux through verified release artifacts.

Read what the compatibility contract protects or see what shipped in Core 0.5.

Folderbase in one minute

npx @folderbase/cli inspect . --json
npx @folderbase/cli init . --dry-run --json
npx @folderbase/cli init .
npx @folderbase/cli validate . --json

Folderbase adds its protocol surface alongside your existing work:

project/
├── .folderbase/
│   └── manifest.json
├── .folderbaseignore
├── FOLDERBASE.md
├── AGENTS.md
└── …your existing files