Quilltap 4.3.1

Quilltap 4.3.1 Release Notes

It is one of life's quieter cruelties that the most precious documents are precisely the ones our couriers seem least inclined to deliver as a complete set. Send a wax-sealed letter and its accompanying postscript into the same mail-bag, and you may be reasonably confident that nine times in ten the postscript will arrive at its destination some hours after the letter — and that in the tenth case it will not arrive at all, having paused, perhaps, to admire the view from a passing barge.

This is, regrettably, the sort of arrangement Quilltap had quietly entered into with its own database. The SQLite engine — for reasons of dazzling write performance — was operating in Write-Ahead Logging mode, a tidy little system in which the main bound ledger (the .db file) is accompanied at all times by a loose-leaf supplement of the most recent entries (the .db-wal and .db-shm files), the two to be reconciled at leisure. On a fast local desk, where both volumes remain side by side, the arrangement is admirable.

In the data directory of a user whose folder lives within iCloud Drive, Dropbox, OneDrive, or Google Drive — which, candidly, is most of you — the arrangement courts disaster. The cloud courier, presented with three files of uncertain provenance, makes its own judgments about which to deliver first. The bound ledger may sail across the Atlantic in good order; the loose-leaf supplement, however, is liable to be left behind on the dock, or to arrive on a different boat, or to vanish entirely should one's machine suffer the indignity of an ungraceful shutdown. When the database is next opened on a different device — or even the same one, the following morning — the supplement and the ledger no longer agree. Recent entries are lost. In the worst cases, the ledger refuses to open at all, citing irreconcilable differences.

The remedy is to cease relying on the supplement. SQLite, with admirable foresight, offers a journal mode called TRUNCATE in which the rollback journal is kept in a single auxiliary file and reduced to zero pages on every commit — meaning the on-disk state, when no write is in progress, is a single self-contained .db file. The cloud courier, presented with one envelope, has nothing to lose along the way. As of 4.3.1, this is the default for all three of Quilltap's databases — the main store, the activity log, and the document mount index — as well as the meta-table connection consulted at startup. Existing databases migrate themselves on first launch; SQLite quietly checkpoints any old supplement into the main ledger as part of the transition, and no user action is required.

For the small population of users running on local SSDs outside any sync folder, where the original WAL performance was a genuine boon, the previous behavior remains available behind the SQLITE_WAL_MODE=true environment variable. The polarity has been inverted: where once one opted out of WAL by setting it to false, one now opts back in by setting it to true. This befits its new station as the unusual choice rather than the default.

No data is lost in the upgrade. The next time you launch Quilltap, the bookkeeping will simply be tidier — and your work will travel between machines without leaving anything behind on the dock.

---

What Changed

• fix: SQLite journal mode default changed from WAL to TRUNCATE. WAL keeps .db-wal and .db-shm files alongside the main .db, which can sync out of order via iCloud Drive / Dropbox / OneDrive / Google Drive and corrupt the database on the next open. TRUNCATE keeps the rollback journal in a single auxiliary file truncated to zero on every commit, eliminating the multi-file sync hazard. Applies to all three databases (main, LLM logs, mount index) plus the startup meta-table connection. Existing databases auto-migrate on first open after upgrade.
• fix: SQLITE_WAL_MODE environment variable inverted from opt-out to opt-in. Set SQLITE_WAL_MODE=true to re-enable WAL when the data directory lives on a fast local SSD that is not synced to the cloud.

---

Installation

Desktop App

Download from the quilltap-shell releases page:

macOS:

1. Download the .dmg file and open it
2. Drag Quilltap to your Applications folder
3. Launch Quilltap from Applications

Windows:

1. Download and run the .exe installer
2. If SmartScreen warns about an unknown publisher, click "More info" → "Run anyway"
3. Launch Quilltap from the Start Menu or desktop shortcut

Linux:

1. Download the .AppImage file, make it executable (chmod +x), and run it
2. Or install the .deb package: sudo dpkg -i quilltap_*.deb

Node.js (any platform)

npx quilltap

Or install globally:

npm install -g quilltap
quilltap

Open http://localhost:3000 in your browser. Requires Node.js 22+. First run downloads ~150-250 MB and caches locally.

Docker

docker pull foundry9/quilltap:4.3.1

Or use the startup scripts:

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/foundry-9/quilltap-server/refs/heads/main/scripts/start-quilltap.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/foundry-9/quilltap-server/refs/heads/main/scripts/start-quilltap.ps1 | iex

---

One does not entrust an heirloom diary to a careless valet who packs the cover and the pages in different trunks. One binds them together, and travels the lighter for it.

-- The Foundry, with all relevant pages bound into a single volume

Installation

Desktop App (recommended)

The Quilltap desktop app (Electron) is available from
quilltap-shell 4.1.1.
Download the release for your platform (macOS, Windows, or Linux).

The quilltap-linux-arm64.tar.gz and quilltap-linux-amd64.tar.gz rootfs
tarballs attached to this release are used by the shell's Lima (macOS) and WSL2 (Windows) VM modes.

Node.js (any platform)

npm install -g quilltap
quilltap

On first run, the CLI downloads the application files (~150-250 MB)
and caches them locally. Subsequent launches start instantly.

Docker

docker pull foundry9/quilltap:4.3.1

See the README for setup instructions.