chessvault Docs
Try the demoDemo

Your chess, in plain files.

A private, self-hosted chess workbench: analysis, an opening explorer, studies, notes, a game collection and puzzle training, all in one folder you own.

The demo needs no install and no account. It runs entirely in your browser.

~/chess-vault/
  • studies/ one study per PGN file, chapters inside it
    • Attacking the castled king.pgn
    • Minority attack.pgn
    • Openings/
  • notes/ markdown, boards in the text
    • Notes on the Catalan.md
    • Opening prep checklist.md
  • games/collection/ one PGN per game
    • Bex N vs Ueda K 2026-02-02.pgn
  • puzzles/history.jsonl every attempt, one line each
  • repertoire/map.json the opening map
  • config.json settings and tokens, never committed
  • .history.git every change, undoable
Your vault as it sits on disk: the files, as any editor or backup tool sees them. No database, no proprietary format. Everything else the app derives from these, and rebuilds if deleted.

contents

What it does

01

Analysis board

Stockfish 19 in the browser, a move tree with variations, comments and arrows, and a game review that scores accuracy.

02

Studies and notes

PGN chapter studies, and markdown notes with interactive boards in the text. The files stay readable in Obsidian.

03

Puzzle training

The Lichess puzzle set by difficulty band, a progress dashboard, scanned tactics books the app reads in itself, and endgame drills against the tablebase.

04

Openings

An explorer over reference databases built from your own PGNs, and a repertoire trainer that rehearses lines against real statistics.

05

Your games

Chess.com and Lichess archives month by month, an annotated collection of the ones worth keeping, and an Insights page that sums them by colour, time control and opening.

06

Database search

Players, openings, positions, material or motifs across millions of games. Exact positions answer in milliseconds, the deep hunts in under a second.

07

The workspace

The board, the engine, the explorer and the whole games browser on one wide screen, so browsing games and analysing stop being page changes.

08

Completely offline

The engine, fonts and icons all ship with it and there are no runtime CDN calls, so pulling the network cable changes nothing.

figures

A closer look

fig. 1
The opening map: a white repertoire as a constellation of moves, each dot named by the opening catalogue and sized by how often the field plays it

The opening map

Your repertoire as a shape rather than a list: the moves you chose, one map per colour, each dot sized by how often the field plays it and badged where you have no answer yet. Link a study and everything below is derived from it, so what the map claims you have prepared is what you have.

fig. 2
One move's panel: the position, its catalogue name, how deep the linked studies prepare it, and the studies and notes tagged onto it

Every move knows what covers it

Select a dot and the opening catalogue names it, while the panel counts how deep your linked studies actually prepare it and how many lines they end in. Notes come along for the reader; only the studies are allowed to say what is prepared.

fig. 3
The Games page's Databases tab: the search box, the result and rating filters, and the table of a 3,000-game reference database

Ask ten million games a real question

Reference databases you build from your own PGNs, searched four ways: a query language for players, openings, events and results; a position ladder from exact, transpositions included, loosening by degrees down to bare pawn structure or material; material situations like rook endings or a queen up; and motifs, from an isolated queen's pawn to a named pawn structure. Exact positions answer in milliseconds at ten million games, and with fast search on the deep hunts come back in under a second.

fig. 4
A note: markdown headings, a live board embedded in the text, and wiki-links to other documents

The files are the format

Studies are PGN, notes are markdown, progress is JSON. No database as the source of truth, no proprietary formats. Backing up is copying a folder, and if this app ever goes away, your chess opens in something else.

fig. 5
The same game collection at phone width, with the bottom bar the app uses there

Or reach it from anywhere

Keeping the vault on this device is the default, but one small Linux box can own it instead and everything else becomes a client: a phone's home screen as a PWA, or the same desktop app pointed at it. Same games, same progress, whichever device you opened.

fig. 6
The board page's engine card: three candidate lines with their evaluations, the opening's name and code, the move list, and the move box

The analysis board

Stockfish 19 in the browser, beside the opening explorer: the engine's lines, the field's replies and the tree of what you played on one screen, and the panel takes the opening's name the moment you make a move.

three ways

Download

Desktop app

windows · macos · linux

By default it keeps the vault in a folder on that device; point it at a server instead if you have one. It updates itself on launch.

The builds are unsigned. On Windows the first launch stops at SmartScreen: choose More info, then Run anyway. On macOS it needs right-click, then Open. The installer's name carries no version; the release page does.

Host it yourself

node

Run it anywhere Node runs. One port serves both the app and its API.

git clone https://github.com/chessvault-app/chessvault.git
cd chessvault
npm install
npm run build
CHESS_VAULT_DIR=/srv/chess-vault npm start

Phone

pwa

Nothing to install: open your server's address and add it to the home screen for a full app with an offline shell.

Try the demo first