nooklet

nooklet is a local-first outliner in the spirit of Logseq. You write in nested bullets, link pages with [[links]] and #tags, keep a daily journal and track tasks. Every device holds the whole graph in SQLite and works offline; a self-hosted server syncs them. AI agents are first-class users: the same operations the app uses are an MCP server and an HTTP API, so Claude Code or Cursor can search your notes, read pages with stable block ids, and edit one bullet at a time. The server also writes every page to plain markdown you can grep, commit or open in Logseq and Obsidian.

MIT licensed, self-hosted, no account, no telemetry.

Project status

The basic functionality is there: you can run a sync server, and the clients (the desktop app, the browser, and the mobile app, tested on an iPhone) sync with it in both directions. The everyday features (editing text, nested bullets, links and tags, journals, tasks, images, search) should work. It is of course not bug-free, and not as feature-rich as projects with years of development behind them. What it does have is a codebase that is easy to hack on, and a design that is extensible from the ground up: one operation registry drives the app, the HTTP API, the MCP server and the typed client, and features can ship as plugins. Expect rough edges and breaking changes before 1.0. See Platform support for what is tested where.

Screenshot placeholder: the journal view with the shelf open.

Quick start

You need Node 24+, pnpm 12 and git.

git clone https://github.com/hnykda/nooklet.git
cd nooklet
pnpm install
pnpm --filter @nooklet/web build
pnpm nooklet serve

Open http://127.0.0.1:6100. To bring a Logseq file graph, open Settings → Import from Logseq and choose the graph's folder (or a .zip of it). From a terminal, pnpm nooklet import /absolute/path/to/graph does the same.

Or skip the build: the Releases page has the desktop apps and an Android APK, and the server runs from a published image:

docker run -d --name nooklet -p 127.0.0.1:6100:6100 -v nooklet-data:/data ghcr.io/hnykda/nooklet:latest
docker exec nooklet /app/node /app/server.mjs token create --label me --scope write --sync

Open http://127.0.0.1:6100 and paste that token. The image never hands out a token on its own (Self-hosting explains why, and how to put it behind HTTPS).

On a Mac, Homebrew installs the desktop app, which runs its own server, and a nooklet command (nooklet import, nooklet mcp --stdio):

brew install --cask hnykda/nooklet/nooklet
xattr -dr com.apple.quarantine /Applications/nooklet.app   # unsigned: after every install/upgrade

The app is not signed or notarized yet; Getting started says what that means.

For several devices, run the server on your Tailscale network with HTTPS and give each device its own token. Getting started walks through it, plus the desktop apps, the iOS app (built from source) and the experimental Android app.

Platform support

Honest status as of the first release. "Built in CI" means a release workflow produces it on every tag, not that anyone has used it.

Platform	How to get it	Status
Server (Docker, from source)	ghcr.io/hnykda/nooklet, or pnpm nooklet serve	Tested; runs the owner's own notes. The arm64 image has only been smoke-tested (starts, answers /healthz).
Web / PWA	Served by the server	Tested; the e2e suite runs it in Chromium and WebKit.
macOS desktop	brew install --cask hnykda/nooklet/nooklet, Releases (.dmg) or pnpm desktop:build	Used daily (Apple Silicon). Unsigned: see Getting started. The Intel build is untested.
iOS	Build from source with Xcode	Tested on the Simulator and one iPhone. No App Store or TestFlight build.
Linux desktop	Releases (AppImage, .deb)	Built in CI, not yet tested by the maintainer.
Windows desktop	Releases (setup .exe)	Built in CI, not yet tested by the maintainer. Unsigned.
Android	Releases (…-android-experimental.apk)	Experimental: never run on a device or emulator by the maintainer.

If you run nooklet on Linux, Windows or Android, a platform report (a short checklist: sync both ways, offline, resume, keyboard, deep links) is the most useful thing you can send. What to expect on Android: Getting started.

Build from source

Building from source covers the toolchain, every build command, the test layers and CI. Build and install nooklet on your iPhone walks through Xcode, signing with a free Apple ID, and pairing the phone with your server.

Documentation

• What nooklet is: who it is for, what is different, non-goals
• Features: what works today, and what is partial
• How it works: SQLite everywhere, the op log, clocks, the mirror
• Sync, offline and conflicts
• Getting started
• Self-hosting: Tailscale, Docker, Kubernetes, proxies, backups, Ollama
• Build and install nooklet on your iPhone: Xcode, free signing, pairing, Web Inspector
• Security model
• For AI agents: MCP, the HTTP API, an example
• Building from source: toolchain, build commands, tests, CI
• FAQ and troubleshooting

Design records live in docs/adr, specifications in docs/spec, and known bugs in docs/BUGS.md.

Not planned

No flashcards, no kanban boards or whiteboards, no real-time co-editing, no hosted service. The scope is an outliner, tasks, links, search, sync and an API agents can use.

Contributing and security

See CONTRIBUTING.md. Report vulnerabilities privately as described in SECURITY.md.

Repository layout

Path	Contents
packages/core	Data model, outline parser and serializer, op log, applyOps, queries
packages/server	SQLite store, sync, HTTP API, MCP server, importer, mirror, embeddings, CLI
packages/plugin-api	Types plugin authors compile against
apps/web	The client; also what the desktop, iOS and Android apps show
apps/desktop	Tauri shell with a bundled server
plugins	Built-in plugins: mermaid, word-count, daily-summary
deploy	Container image and an example Kubernetes chart
e2e	Playwright tests against a real server and a production build

License

MIT