qnotesd

Local daemon for syncing the Quickshell TODO widget with a SQLite-backed task store and Codex prompt context.

Widget

This is built for a local Quickshell TODO widget on Linux.

Quickshell is a QtQuick/QML desktop-shell toolkit for building Linux bars, widgets, lock screens, and similar desktop components. Install it from the upstream install guide:

https://quickshell.org/docs/v0.3.0/guide/install-setup/

The package is usually named quickshell. Upstream documents packages for Arch, Fedora, Debian testing/unstable, Nixpkgs, Ubuntu via PPA, Gentoo, Guix, and manual builds.

qnotesd does not install Quickshell and does not provide the visual TODO widget. It syncs a Quickshell configuration that writes its TODO state to:

~/.local/state/quickshell/user/todo.json

That file is expected to be a JSON array of entries with at least content and done fields. qnotesd adds a qnotesd metadata object to entries it has imported and preserves other widget fields when it writes the file.

Build

make build
make test

Install

From a checkout:

make install-start

That builds bin/qnotesd, creates config/env files, runs migrations, installs the Codex hook, installs the systemd user unit, enables it, and starts it.

To install without starting the service:

make install

If qnotesd is already on PATH:

qnotesd install --all --enable --start

Uninstall managed integration files:

make uninstall

Config and SQLite data are left in place.

Paths

• Config: ~/.config/qnotesd/config.toml
• Env overrides: ~/.config/qnotesd/env
• Database: ~/.local/share/qnotesd/qnotesd.sqlite
• TODO widget: ~/.local/state/quickshell/user/todo.json

Supported env keys:

• OPENROUTER_API_KEY
• OPENROUTER_MODEL
• QNOTESD_TODO_PATH
• QNOTESD_DB_PATH

Env values override TOML. Env path values may use $HOME; TOML paths intentionally do not expand environment variables.

Commands

qnotesd migrate
qnotesd daemon
qnotesd doctor
qnotesd inspect todo
qnotesd inspect items --status open
qnotesd hook prompt
qnotesd observe --json
qnotesd complete --json

TODO entries are imported directly as tasks. The classifier is not used for TODO widget entries.

Raw TODO text is retained locally in SQLite without at-rest encryption. inspect raw redacts content by default; use --show-raw only for local debugging.