A personal Knowledge OS fused with an interactive-fiction engine. Your notes are the world. Your stories run on a compiler you own. Everything local, everything yours.
Built in the open, one fable at a time — a 2,026-feature journey from a blank repo to a complete personal-software suite. The plan is complete: every feature shipped, or honestly deferred (
[~]) with a reason. ~4,100 tests green, and not a byte of your data leaves your machine.👉 Never installed something like this before? Jump to Install Fables — the gentle, step-by-step guide.
Fables combines a local-first note-taking system with Fable Forge — a custom language and
bytecode VM for interactive storytelling. Write notes with [[wikilinks]], explore them as a graph,
tag and search them, journal daily. Then write branching stories in the Forge language — prose-first
syntax that compiles to bytecode — where your notes are the lore: characters are entities, choices
read and write your knowledge base, and the world the story inhabits is the one you actually keep.
It runs on your own machine, reads beautifully on an iPhone as a PWA over
Tailscale, and stores everything in ~/.fables. No cloud. No fees. No tracking.
- Local-first, genuinely. SQLite on your disk. Optional token auth. Tailnet-only access. AI is optional and, when on, secret/encrypted content is filtered out before any model ever sees it.
- You own the story engine. Not a wrapper around someone else's format — a real lexer, parser, compiler, and stack-based VM you can read end to end.
- Notes ⇄ stories, both directions. Stories branch on knowledge state via
@entity.fieldbindings and[[lore]]references; effects write journal entries and mutate entity fields. - Honest by construction. Every feature is tracked in
FEATURES.md. When something is only partly done, it's marked[~]with the reason — never quietly overclaimed.
The plan is two tiers and an encore — 2,026 features (yes, like the year). Here's where we are:
The complete Knowledge OS + Fable Forge: Markdown notes, wikilinks, backlinks, graph view, full-text + semantic search, daily journal, tags, notebooks, saved queries, templates; the Forge DSL & VM (knots, choices, variables, conditionals, diverts, saves, playback); the fusion of the two; an offline-first PWA with op-log sync; security hardening; accessibility; backups; local analytics. Shipped.
| Epic | Theme | Status |
|---|---|---|
| 11 — Plugins & Extensions | A sandboxed plugin runtime + capability system + SDK | ✅ Complete |
| 12 — Real-Time Collaboration | CRDT core (Yjs), live editing, sharing model, merge history | ✅ Complete |
| 13 — Encrypted Vault & Security | Argon2id + XChaCha20 vault, secret notes, audit log, compliance, SSRF guard | ✅ Complete¹ |
| 14 — AI Co-Writer & Modality Mesh | Local-first AI: RAG, note intelligence, co-writer, streaming, llama.cpp, opt-in Claude | ✅ Complete |
| 15 — Importers & Interop | 19 importers, 6 export formats, format-detection, round-trip fidelity | ✅ Complete |
| 16 — Canvas & Spatial Views | Infinite canvas, world atlas, spatial thinking | ✅ Complete |
| 17 — Audio Fables | Narration, soundscapes, the audio modality |
✅ Complete |
| 18 — Spaced Repetition & Learning | FSRS-5 scheduler, cards/decks, Anki interop, learning insights | ✅ Complete |
| 19 — Story Interop & Distribution | .fablepack/.fablearchive, Ink/Twee import, generative art |
✅ Complete |
| 20 — Multi-Vault, Automation & Power Tools | Vault registry, automation, webhooks, scripting, bulk ops, FQL v2, power tools | ✅ Complete |
¹ The vault's cryptography, secret-notes key path, audit log, and security tier are shipped and tested.
A few deep-integration and multi-device-transport pieces remain [~] (deferred-with-reason) — the
honest edges, listed in FEATURES.md.
22 design-led features to make it gorgeous — OKLCH perceptual color, editorial typography on a baseline grid, GSAP-class spring motion + view transitions, WebGL/GLSL showpieces (ambient gradient mesh, glass materials, a GPU-rendered knowledge graph), all reduced-motion- and battery-aware. Apple restraint, Pentagram craft. The computational design-system core (color/type/motion) is shipped and tested; the GPU/CSS rendering surfaces are the web app's to paint. The 22 that round the plan up to 2,026.
- AI Co-Writer (Epic 14): "ask your vault" RAG with cited, grounded answers and an honest "no good sources" refusal; note intelligence (summarize, tag, outline, rewrite); a story & character co-writer; an opt-in Claude cloud adapter behind an egress-consent gate; a global kill switch; and a hard wall that keeps encrypted content out of every prompt.
- Importers & Interop (Epic 15): import from Notion, Apple Notes, Evernote, Roam, Logseq, Bear, Day One, Simplenote, Google Keep, Standard Notes, Joplin and any folder of Markdown — with a dry-run report, provenance, resume, and one-click rollback on every import. Export to JSON (lossless), Obsidian, Notion, Logseq, a static HTML site, and a print-ready PDF book, scoped by an FQL query if you like, with a round-trip fidelity test guarding against silent loss.
Fables is written with Claude Code driving a small formation of specialized agents in parallel: an
orchestrator that owns the shared seams (registries, routes, the green-gate), two code lanes
working on disjoint directories so they never collide, and a docs lane. Each unit lands only when
pnpm test, pnpm typecheck, and pnpm lint are all green, then it's committed and pushed. The whole
story — decisions, dead ends, retrospectives — lives in docs/devlog/.
It's an experiment in long, autonomous, honest building: the agents resolve their own problems and
keep going, but every claim is backed by a passing test and an unflinching FEATURES.md.
New to this kind of thing? This section is for you. It assumes zero prior experience. Take it slowly; you can't break anything.
- It's free software you run on your own computer. There's no App Store, no website to sign up for, no subscription, and nothing of yours ever leaves your machine.
- There's no App-Store/installer package (yet), but it's friendly. A double-click launcher handles first-time setup and starting for you, and if you prefer, every step is plain copy-and-paste into a Terminal — we explain each line. The only one-time chore is installing two free tools (Step 1). Budget about 20–30 minutes the first time; after that, opening Fables is one double-click.
- Where it lives: put it in any folder you like — your home folder or
Documents is perfect, and it doesn't need to be anywhere special. One nuance:
if you plan to keep tinkering with Fables itself using Claude Code (e.g.
cowork / dispatch), put the folder somewhere Claude Code is allowed to work —
many people keep a dedicated projects/Claude folder for exactly this. Either
way, your notes live separately in
~/.fables, so moving the code folder later never touches your data. - Two devices, two jobs: your laptop runs Fables (it's the engine, always the "real" copy). Your iPhone simply opens it in Safari over your private network — you don't copy any code onto the phone.
- What do you connect it to? Nothing — but you can. Fables works completely on its own (offline, private, no accounts or keys). When you want more, it plugs into local or cloud AI (Ollama, llama.cpp, or the Claude API), generated art (a local or cloud ComfyUI diffusion server), and voices (Piper) — see Step 7. None are required, and any cloud option stays off until you explicitly opt in.
After you've done the one-time setup in Step 1 below (install Node.js + pnpm)
and downloaded Fables (Step 2), you can skip the typing entirely and just
double-click the launcher in the Fables folder:
- Windows:
start-fables.cmd - Mac:
start-fables.command(first time: right-click → Open to get past the "unidentified developer" prompt) - Linux:
start-fables.sh
The first time, it sets itself up (downloads components and builds — a few minutes); after that it just starts Fables and opens it in your browser. Keep the little window it opens running while you use Fables; close it to stop. If you'd rather type the commands yourself (or something goes wrong), the manual steps below do exactly the same thing.
- Mac and Linux — follow the steps as written.
- Windows — works natively, no WSL or Linux needed. Use PowerShell (search "PowerShell" in the Start menu) wherever the steps say "Terminal." The database component ships a ready-made Windows build, so there's nothing to compile. The only Windows-specific detail is how you set optional settings like AI keys — noted in Step 7.
Fables runs on Node.js (the engine) and uses pnpm (which fetches its building blocks). You install these once.
-
Node.js (version 22 or newer). Go to nodejs.org and download the LTS installer for your system, then run it and click through. (On Mac with Homebrew:
brew install node. On WSL/Ubuntu:sudo apt update && sudo apt install -y nodejs npm.) -
pnpm. Open your Terminal (on Mac: Terminal app; on Windows: the Ubuntu app; on Linux: your terminal) and run:
npm install -g pnpm
To check both worked, run node --version (should say v22 or higher) and
pnpm --version (should say 10 or higher).
Option A — the simple way (no extra tools): on the GitHub page, click the green Code button → Download ZIP, then unzip it wherever you like.
Option B — the better way for getting updates later (needs git):
git clone https://github.com/visualsbytheRob/Fables.gitEither way, you now have a folder called Fables. In your Terminal, move into
it (type cd then drag the folder onto the Terminal window to fill in the path,
then press Enter):
cd FablesRun these three commands one at a time (the first two take a few minutes the first time — that's normal):
pnpm install # fetches Fables' building blocks
pnpm build # assembles the app
pnpm start # starts FablesWhen it's running you'll see log lines and it will keep running — that's good. Leave this Terminal window open; closing it stops Fables. (To stop it on purpose, click the window and press Ctrl + C.)
(Tip: instead of these three commands you can just double-click the launcher — see the easiest way above.)
Want a few example notes and a sample story to explore first? Run
pnpm seed:demoonce, thenpnpm start.
Open a web browser and go to:
http://localhost:4870
That's Fables. Have a click around — make a note, try a [[wikilink]]. Everything
you do is saved on your own machine (in a hidden folder called .fables in your
home directory).
Tailscale is a free, private network that securely
connects your devices to each other — and only yours. It's how your phone
talks to your laptop without exposing anything to the public internet, and it
provides the secure https:// address an installable phone app needs.
-
Make a free Tailscale account at tailscale.com.
-
Install Tailscale on your laptop and sign in (Mac · Windows · Linux). On Mac/Linux you can also run
sudo tailscale up. -
Install the Tailscale app on your iPhone (App Store) and sign in with the same account.
-
With Fables still running (Step 3), tell Tailscale to share it. In a Terminal on your laptop:
tailscale serve --bg 4870
Tailscale prints a secure address like
https://your-laptop.your-tailnet.ts.net. -
On your iPhone, open Safari and go to that exact
https://…ts.netaddress. Fables loads. 🎉
(There's a deeper walkthrough, including troubleshooting, in docs/tailscale.md.)
Fables is a PWA (Progressive Web App) — modern browsers can "install" a website so it gets its own icon and opens in its own window, just like a normal app. No App Store needed.
- On your iPhone (Safari): with Fables open, tap the Share button (the square with an up-arrow) → Add to Home Screen → Add. You now have a Fables icon on your home screen that opens full-screen.
- On your laptop (Chrome or Edge): open
http://localhost:4870, then click the Install icon at the right of the address bar (a little screen-with-arrow) → Install. You'll get a Fables icon you can pin to your dock / taskbar / Start menu and launch like any app. (Safari on Mac: File → Add to Dock.)
"Is there a one-click
.exe/.msiinstaller?" Not yet — and here's the honest state of it. Two pieces already give you the app-like experience: the double-click launcher (start-fables.cmd) starts the engine without typing, and the PWA install above gives you a real Start-menu/taskbar icon. What's not here yet is a single signed installer that bundles everything and auto-starts on boot — that needs a Windows build-and-code-signing pipeline (otherwise Windows SmartScreen warns users), so it's a deliberate future enhancement rather than something half-built. If you'd like Fables to start automatically when Windows boots in the meantime, that's a small one-time setup (a shortcut tostart-fables.cmdin the Startup folder, or a Task Scheduler entry) — ask and we'll add the exact steps.
You don't need any of these to use Fables. Everything except these specific extras already works out of the box. But Fables is built to grow — it has a pluggable "modality mesh" where you can light up AI writing help, generated art, and spoken narration whenever you want. You choose local (runs on your own machine, fully private) or cloud (a hosted service, faster/stronger but data leaves your machine — so it's always opt-in and consent-gated).
How to give Fables a setting: these are turned on with environment variables at start time.
- Mac / Linux: put them in front of the start command —
ANTHROPIC_API_KEY="sk-ant-…" FABLES_COMFY_URL="http://127.0.0.1:8188" pnpm start- Windows (PowerShell): set them first, then start —
$env:ANTHROPIC_API_KEY="sk-ant-…", thenpnpm start(they last for that window; usesetx ANTHROPIC_API_KEY "sk-ant-…"to remember them permanently).Using the double-click launcher? Open it in a text editor and add your settings near the top — there's a comment showing where.
Pick either a local model or Claude (or both — Fables prefers whichever is available, and you can route per-feature):
| Option | Private? | How to set it up |
|---|---|---|
| Ollama (local, easiest) | ✅ 100% on-device | Install Ollama, run ollama pull llama3.1 (or any model). Fables auto-detects it on the default port. Override with FABLES_OLLAMA_URL. |
| llama.cpp (local) | ✅ 100% on-device | Run llama-server. Set FABLES_LLAMACPP_URL if it's not on http://127.0.0.1:8080. |
| Claude API (cloud) | Get a key at console.anthropic.com, set ANTHROPIC_API_KEY="sk-ant-…". Two locks: the key enables the adapter, and the cloud path stays off until you explicitly enable it and grant egress consent (via Fables' AI settings, or the /api/v1/ai/settings endpoint). Nothing is sent until you do. A global kill switch turns all AI off instantly, and secret/encrypted notes are filtered out before any prompt is built. |
Fables talks to ComfyUI — the
popular node-based diffusion engine — over its HTTP API. Same local-or-cloud
choice, pointed at with one variable, FABLES_COMFY_URL:
| Option | Private? | How to set it up |
|---|---|---|
| ComfyUI Desktop / local (recommended) | ✅ 100% on-device | Install ComfyUI Desktop (or run ComfyUI yourself), load a diffusion model (SDXL, Flux, …), and set FABLES_COMFY_URL="http://127.0.0.1:8188". No consent needed — it's your machine. |
| ComfyUI in the cloud (hosted) | Point FABLES_COMFY_URL at your hosted ComfyUI endpoint. Because images would leave your machine, the cloud path stays off until you grant egress consent in Fables — exactly like the Claude path. |
If ComfyUI isn't configured, Fables falls back to a clean, typographic SVG cover automatically — stories still get art, just generated locally without a model.
| Option | Private? | How to set it up |
|---|---|---|
| Piper (local) | ✅ 100% on-device | Install Piper and download a voice model; Fables uses it for narration & audiobooks. |
The golden rule: if an optional tool isn't present, the matching feature simply stays quiet — Fables never breaks because a power-up is missing, and nothing ever leaves your machine unless you explicitly turn on a cloud option and accept its consent prompt.
- To stop Fables: click its Terminal window and press Ctrl + C.
- To start it again later: open a Terminal,
cdinto theFablesfolder, and runpnpm start. (You onlypnpm install/pnpm buildagain after you update to a new version.) - To update to the latest version: if you used
git clone, rungit pullthenpnpm install && pnpm build. If you downloaded the ZIP, download a fresh ZIP and rebuild. Your notes (in~/.fables) are untouched by updates. - Want Fables to start automatically when your laptop boots? That's a more advanced setup (a background service); ask and we can add it.
command not foundforpnpmornode— Step 1 didn't finish; reinstall Node.js, close and reopen the Terminal, and try again.- "port already in use" — something else is on port 4870. Start on another port
(Mac/Linux:
PORT=4871 pnpm start; Windows PowerShell:$env:PORT="4871"; pnpm start), thentailscale serve --bg 4871. - The phone can't reach it — make sure (a) Fables is still running on the
laptop, (b)
tailscale serveis running, and (c) both devices are signed into the same Tailscale account. Runpnpm doctoron the laptop for a quick health check. - Still stuck? Open an issue on GitHub, or see docs/troubleshooting.md.
Start with docs/architecture.md for the big picture, then the import guides in
docs/ (Notion, Evernote, Apple Notes, outliners, …) and docs/ai.md for how
the local-first AI works. For iPhone PWA setup, see docs/tailscale.md.
# prerequisites: Node 22+ (see .nvmrc), pnpm 10+
git clone https://github.com/visualsbytheRob/Fables.git
cd Fables
pnpm install
pnpm doctor # verifies your environment
pnpm dev # starts the server + web apptailscale serve --bg <server-port>Then open the printed https://<machine>.<tailnet>.ts.net URL on your iPhone and Share → Add to
Home Screen to install the PWA. Full guide in docs/tailscale.md.
| Path | What it is |
|---|---|
apps/server |
Fastify + SQLite API server, serves the built web app |
apps/web |
React PWA (Vite) |
packages/core |
Domain types, schemas, shared utilities |
packages/forge-dsl |
The Fable language: lexer, parser, compiler |
packages/forge-vm |
Bytecode VM that plays compiled stories |
packages/sync |
Offline-first op-log sync engine |
packages/ui |
Design-system primitives |
pnpm dev # run everything in watch mode
pnpm build # production build
pnpm test # run all test suites
pnpm lint # eslint
pnpm typecheck # tsc across the workspace
pnpm format # prettierPrecedence: CLI flags > environment > fables.config.json > defaults.
| Setting | Flag | Env | Default |
|---|---|---|---|
| Port | --port |
PORT |
4870 |
| Host | --host |
HOST |
127.0.0.1 |
| Data dir | --data-dir |
DATA_DIR |
~/.fables |
| Log level | --log-level |
LOG_LEVEL |
info |
--open opens a browser after start. Effective config is served at GET /api/v1/config. No secrets
ever live in this repo, and your notes never leave your machine.
2,026 features. Two tiers and an encore. One fable at a time.