Skip to content

Getting Started

Installation

Tessera is source-distributed: clone earthgraph/tessera, build locally, and run the app yourself. The project does not publish or maintain prebuilt installers.

Platform Build command Typical outputs (local build)
macOS ./build-release.sh Universal .app (optional .dmg with BUILD_DMG=1)
Linux ./build-release.sh .deb, .rpm, and .AppImage under tauri-desktop/src-tauri/target/release/bundle/
Windows .\build-release.ps1 .msi and NSIS .exe under tauri-desktop\src-tauri\target\release\bundle\

Requirements: Node.js 20+, Rust toolchain, and Tauri v2 prerequisites for your OS.

On Arch Linux, the simplest path is usually the AppImage (no native pacman bundle from Tauri):

sudo pacman -S --needed fuse2    # required to run most AppImages
chmod +x tauri-desktop/src-tauri/target/release/bundle/appimage/*.AppImage
./tauri-desktop/src-tauri/target/release/bundle/appimage/*.AppImage

If FUSE is unavailable, try ./Tessera_*.AppImage --appimage-extract-and-run.

AppImages are large (often 70 MB+) and are built against your system’s glibc — fine for local use on the same machine, less portable than they look. To skip AppImage and build only .deb/.rpm: BUILD_APPIMAGE=0 ./build-release.sh. Alternatively convert the .deb with debtap if you want a local pacman package.

Git tags (for example 0.1.18) mark source snapshots for reference; you still build from that checkout.

Unsigned builds (macOS Gatekeeper)

Release scripts produce unsigned local builds unless you add your own signing. On first launch, macOS may warn that the app is from an unidentified developer — right-click the app, choose Open, and confirm.

First launch

When you open Tessera, you'll see the Vault Navigation screen — a gallery of your projects (workspaces).

  1. Click New Project to create your first workspace.
  2. Give it a name (letters, numbers, hyphens, and underscores only).
  3. You'll land directly on the lighttable grid, ready to create notes.

Creating your first note

  1. Click the + New Note button in the top-right corner.
  2. Enter an ID for the note (e.g. brainstorm_ideas). This becomes the filename.
  3. Click Create — a new blank card appears on the grid.
  4. Click the card body to open the Markdown editor.
  5. Type some text, then click Save to render your Markdown.

That's it — you've created your first Tessera note. It's saved as a plain .md file inside your project folder.

A faster way to create notes is from the search bar. Inspired by Notational Velocity, search filters notes dynamically as you type. If no matching note is found, press Enter to create a new note instantly.

Where is my data?

Tessera stores all data as plain files on your filesystem:

your-project/
├── order.json           # Card arrangement
├── tags.json            # Tag assignments
├── my_note.md           # A note's Markdown content
├── my_note/             # Associated images for that note
│   ├── photo.png
│   └── diagram.jpg
└── another_note.md

You can open the project folder directly from Tessera using the Open in Finder button (macOS) or equivalent on other platforms.

Using the agent skill with coding agents

Tessera projects work well with agent-driven edits because the data model is plain files (.md, order.json, tags.json).

This repository ships a skill at skills/tessera/SKILL.md that documents the vault contract:

  • note IDs map to filenames (note_id.md)
  • order.json controls card order
  • tags.json stores tag arrays by note ID
  • images for a note live under note_id/

In Cursor, copy or link the skill into your skills directory, then reference it as @skills/tessera (or your chosen path). In other tools, point the agent at the SKILL.md file directly.

Example prompt:

Read skills/tessera/SKILL.md and add three notes to my-project/.

This has been tested with both hosted and local models; quality varies by model, but the file-based workflow is robust.

Current testing has focused on project-level editing (agent targets one project directory). Vault-level orchestration across multiple nested projects may need more explicit prompts about which project to edit.

Next steps

Note: live refresh is not yet implemented. Concurrent editing of the same project (for example Tessera open while a human or agent edits the same files elsewhere) is not recommended because the last write wins. Asynchronous workflows are generally safe: let the external process finish, then reopen/reload the project in Tessera before continuing.