# TigerFS
A versioned filesystem backed by PostgreSQL, and a filesystem interface to PostgreSQL. Built for agents.
Every file is a real PostgreSQL row and every write is an atomic transaction. Agents and humans share one transactional source of truth through ordinary files, with no sync protocols and no coordination layer. The filesystem is the API.
TigerFS runs as a local daemon: it exposes a mount over FUSE (Linux) or NFS (macOS), translates filesystem calls into SQL, and dispatches them to a local or remote PostgreSQL database, so ordinary Unix tools operate directly on real database rows.
Website: https://tigerfs.io
Documentation: https://tigerfs.io/docs/
File-first mode (versioned workspaces for agents): https://tigerfs.io/file-first/
Data-first mode (mount any Postgres as files): https://tigerfs.io/data-first/

## Installation
curl -fsSL https://install.tigerfs.io | sh
Works on Linux (FUSE) and macOS (NFS), with no external dependencies on either.

## Quick Start
tigerfs mount postgres://localhost/mydb /mnt     # mount any self-hosted Postgres
tigerfs create ghost:my-project /mnt             # or spin up an instant Ghost database
tigerfs create tiger:my-project /mnt             # or a Tiger Cloud database (Postgres + TimescaleDB)
echo "markdown,history" > /mnt/.build/notes      # create a versioned workspace
echo "# Hello" > /mnt/notes/hello.md             # write a file (one atomic transaction)
tigerfs unmount /mnt

## Connection Strings
- postgres://user@host/db   any self-hosted or managed PostgreSQL
- tiger:<service-id>        Tiger Cloud (run `tiger auth login` once)
- ghost:<service-id>        Ghost (run `ghost login` once)
Used by mount, create, fork, and migrate. Set a default backend in config to omit the prefix.
Choose Tiger Cloud for production and time-series workloads (Postgres + TimescaleDB); choose Ghost for instant, disposable databases and exploration.
Tiger CLI: https://github.com/timescale/tiger-cli    Ghost CLI: https://github.com/timescale/ghost

## Highlights
- Two modes on one transactional engine: file-first (versioned agent workspaces) and data-first (mount any Postgres as files).
- ACID transactions and true concurrent access; changes are visible to all readers immediately, with no pull, push, or merge.
- Operation log, named savepoints, and atomic undo (per operation, per savepoint, or per user). Undo is itself logged and reversible.
- Pipeline queries push filters, ordering, and pagination down to a single SQL query.
- Works with any tool that speaks files: Claude Code, Cursor, grep, vim, cat, awk.
- Agent skills auto-install at mount time for Claude Code, Cursor, Gemini CLI, Codex, and others.
- Backends: any PostgreSQL, plus Tiger Cloud and Ghost by service ID. History and undo require TimescaleDB (included with Tiger Cloud and Ghost).

## Two Modes
- File-first: write markdown or plaintext into versioned workspaces. Atomic writes, version history, savepoints, and atomic (per-user) undo. Good for multi-agent knowledge bases, task queues, and parallel agent work.
- Data-first: mount any Postgres database as a directory. Tables are folders, rows are files, columns are fields. Explore with ls/cat/grep; chain pipeline filters that push down to SQL. Writes are PATCH-style; data-first writes are permanent (use a file-first workspace with history for reversible writes).

## Formats
- File-first: YAML frontmatter maps to columns; the body below it becomes the row's text column.
- Data-first: read a row in any format by extension: 123.json, 123.csv, 123.tsv, 123.yaml. Navigate into a row (123/) to read columns as files (123/email.txt). JSON writes use PATCH semantics (only the keys you include change).

## Core CLI Commands
- mount - Mount a database to a local directory
- unmount - Unmount a mounted database
- create - Create a new cloud database (e.g. tigerfs create tiger:my-db /mnt)
- fork - Fork (clone) a database to experiment safely
- list - List available databases (cloud backends)
- status - Show status of all active mounts
- info - Inspect a mount (add --json for scripting)
- config - Show or modify configuration
- migrate - Apply pending database schema migrations
- test-connection - Test connectivity to a database without mounting
- version - Print TigerFS version information

## Dot-directory control surface
Every directory is extended with hidden dot-directories (use ls -a to see them):
- .build/ - create a file-first workspace (e.g. echo "markdown,history" > .build/notes)
- .info/ - table metadata: columns, count, schema, indexes
- .by/ .filter/ .order/ .columns/ .first/ .last/ .sample/ .export/ - pipeline query segments, composed into one path and pushed down to a single SQL query
- .import/ - bulk load (.append / .sync / .overwrite)
- .create/ .modify/ .delete/ - schema management (staged, then .commit)
- .history/<file>/ - timestamped version snapshots; .id gives a file's stable UUID
- .log/ - operation log; filter via .by/file_id|user_id|type, diff an edit via before/current/after
- .savepoint/<name>.json - named bookmarks (auto-savepoints via --auto-savepoint-interval)
- .undo/ - atomic undo: id/<log_id>, to-id/<log_id>, to-savepoint/<name>, with optional .by/user_id; preview via .info/summary, apply via .apply
- .tables/<workspace>/ - data-first access to file-first backing tables (bypasses history)

## Agent Skills
TigerFS ships agent skills (for Claude Code, Cursor, Gemini CLI, Codex, Windsurf, and others), auto-installed at mount time. They teach the filesystem interface (reading, writing, searching, pipeline queries, and the savepoint/undo workflows) so you can work in natural language without learning the paths. See https://tigerfs.io/docs/#agent-skills.

## Canonical Pages
- Home: https://tigerfs.io/ - The filesystem is the API.
- File-first mode: https://tigerfs.io/file-first/ - A versioned filesystem for agents; savepoints and atomic undo.
- Data-first mode: https://tigerfs.io/data-first/ - Mount any PostgreSQL database and query it as files.
- Docs: https://tigerfs.io/docs/ - Install, CLI reference, quick start, modes, agent skills, configuration, upgrading.
- Quick start: https://tigerfs.io/docs/#quick-start - Mount a database, write a file, unmount.
- GitHub: https://github.com/timescale/tigerfs - Source, issues, and design docs.
- Tiger Cloud: https://www.tigerdata.com/cloud - Managed PostgreSQL with TimescaleDB.
- Ghost: https://ghost.build/ - Instant databases for agents.