Skip to content

Vaults & Projects

Tessera organizes your work into projects (or, a set of projects within a vault). Each project is an independent collection of notes and images stored in its own folder.

The Vault screen

When you first open Tessera, you land on the Vault Navigation screen. This shows all your projects as clickable cards.

  • Click a project card to open it and view its notes on the lighttable grid.
  • Click the home icon (🏠 Vault) in any project to return to the vault screen.

Creating a project

  1. Click New Project on the vault screen.
  2. Enter a name (letters, numbers, hyphens, underscores). Spaces and special characters are converted to underscores.
  3. Click Create. You'll be navigated directly into the new empty project.

Deleting a project

Click the trash icon on a project card in the vault screen. Confirm the deletion when prompted.

Warning

Deleting a project permanently removes all its notes, images, and metadata from disk.

Opening the project folder

While inside a project, click the Open in Finder button (macOS) or equivalent to open the project's directory in your system file manager. This is useful for:

  • Browsing raw Markdown files
  • Managing images manually
  • Copying files for use elsewhere
  • Initializing a Git repository for version control

If you edit project files externally (for example with scripts, Git operations, or coding agents), reopen the project (or restart Tessera) to refresh what is shown in the app. A dedicated in-app refresh action is planned but not yet available.

For agent workflows and the bundled skill, see Getting Started.

Data structure

Each project is a flat directory with the following structure:

project-name/
├── order.json           # Array of note IDs defining grid order
├── tags.json            # Tag assignments for all notes
├── note_one.md          # Note content (Markdown)
├── note_one/            # Images attached to note_one
│   └── screenshot.png
├── note_two.md
└── note_two/
    └── diagram.svg

This structure is fully portable — you can copy, move, or version-control entire projects.

The topology constraint is intentional:

  • Project mode: one project directory; per-note image folders are one level below note IDs.
  • Vault mode: a directory of projects; each project keeps the same flat project topology.
  • Not supported: nested projects inside projects (deeper project trees are out of scope). A nested folder can still be treated as a project if you open that folder directly and it contains the expected Markdown project files.

Image-folder naming rule (strict):

  • For each note note_id.md, the image directory must be exactly note_id/ (same stem, no .md).

Topology map (projects vs vaults)

flowchart LR
    V["vault/ (optional)"]
    V --> P1["project_alpha/"]
    V --> P2["project_beta/"]

    P1 --> P1A["order.json"]
    P1 --> P1B["tags.json"]
    P1 --> P1C["description.md"]
    P1 --> P1D["description/"]
    P1D --> P1E["img_*.png"]
    P1 --> P1F["feature_details.md"]
    P1 --> P1G["feature_details/"]
    P1G --> P1H["img_*.png"]

    P2 --> P2A["(same flat project shape)"]

    P1 -. "unsupported" .-> N["nested_project/"]

Command-line usage

Tessera supports launching directly into a specific project from the command line:

tessera --project /path/to/project
tessera --vault /path/to/vault

on MacOS one needs to provide the full path, or set an alias, i.e.:

/Applications/Tessera.app/Contents/MacOS/tessera --project ~/test-project/

one could otherwise add such an alias:

alias tessera="/Applications/Tessera.app/Contents/MacOS/tessera"

Or, shorter: Use -p (project) or -v (vault) as shorthand flags, e.g.

/Applications/Tessera.app/Contents/MacOS/tessera -p ~/test-project/