katNotes
Personal notes and a daily journal in plain markdown (TUI, GUI & CLI).
Notes are ordinary markdown files with YAML front matter: no database and no lock-in. One Go core sits behind three frontends, so they all read and write the same files:
katnotes: a CLI, and with no arguments a TUI (Bubble Tea, pure Go, no CGO)katnotes-gui: a desktop app built with Wails v3 and Svelte, with an in-place editor
Features
- Pages and daily journal entries, with page templates and pinned notes
- Search by fuzzy name, tags (
work -done) or full text, plus quick open (Ctrl+P) and saved searches - Links and backlinks using ordinary relative markdown links, so katdown and GitHub can follow them too. Renaming a page updates every link to it
- Markdown tasks with due dates and priorities, and a view of every task across your notes
- A
:command window shared by the TUI and GUI, with completion for note titles, tags and front matter fields - Lua commands: your own
:commands in both apps, and/commands while typing in the GUI editor - Light/dark themes shared by the TUI and GUI, with your own theme files
- Git sync:
:synccommits the notes folder, pulls and pushes - Your editor and viewer: edit in whatever you set in the config, and preview with katdown (or glow, mdcat…)
- Fast with lots of notes: notes are cached, so lists and searches stay quick even with thousands of files
A note
---
title: Hello World
tags: [idea, go]
created: "2026-11-16T20:37:44-07:00"
updated: "2026-11-16T20:37:44-07:00"
---
# Hello World
Body text…Pages live in ~/KatNotes/pages/ and journal days in ~/KatNotes/journal/YYYY-MM-DD.md. Front matter fields katNotes doesn't know are kept, and files with no front matter still work.
Tasks
Tasks are plain GFM checkboxes, with optional metadata in a block at the end of the line:
- [ ] Call the plumber {due:2026-11-20 pri:high}
- [ ] Draft report #work {due:2026-11-21}
- [x] Pay rent {due:2026-11-01 done:2026-10-30}
- [ ] Book venue {due:2026-12-01 note:"ask about parking"}The preview shows the block as chips and marks overdue tasks. Keys include due, pri (high / med / low), done (added when you check a task) and start, and any other key is kept and filterable. Because it's all plain text, searching is just grep:
rg 'due:2026-11' ~/KatNotes # due this month
rg '\{[^}]*pri:high' ~/KatNotes # high priorityCLI
katnotes # TUI
katnotes new "Title" -t a,b # new page, opens your editor
katnotes new --template meeting "Standup"
katnotes today # today's journal entry
katnotes journal -3 # three days ago
katnotes todo call Sam {due:fri} # add a task to today's journal
katnotes search budget "next week"
katnotes tasks list --overdue --pri high
katnotes backlinks groceries
katnotes sync # git commit, pull --rebase, pushEvery command accepts --json for scripting.
TUI keys
| Key | Action |
|---|---|
j / k, gg / G | move, first / last |
tab, 1–4 | Pages, Journal, Tags, Tasks |
n | new note |
enter / e | edit in your editor |
p | preview (katdown, glow…) |
J | today's journal |
/, ctrl+p | search, quick open |
T, L | edit tags, link to another note |
gb / gf | backlinks / links |
x, @, p | tasks: check, set due date, cycle priority |
: | command window |
? | help |
Desktop app
The GUI has a sidebar (Pages, Journal, Tags and Tasks tabs, plus search) and an editor with edit, split and preview modes. Notes autosave as you type, and it won't overwrite a note that changed on disk.
- Type
[[to link to a page or journal day ([[today,[[friwork too) - Type
/for commands like/todo,/due,/pri,/today,/time, plus your own Lua ones Ctrl+Entermakes a line a task or checks it;{on a task line suggests keys and valuesCtrl+Shift+Tshows every task from every noteCtrl+Shift+Zhides the sidebar and top bar for focus- A Settings dialog covers every option
Lua commands
-- ~/.config/katnotes/commands/wordcount.lua
return {
description = "Count the words in the note",
run = function(ctx)
local n = 0
for _ in ctx.body:gmatch("%S+") do n = n + 1 end
return ctx.note.title .. ": " .. n .. " words"
end,
}: commands go in commands/ and work in both apps; / commands go in slash/ and work in the GUI editor.
Settings
notes_dir = "~/KatNotes"
editor = "" # falls back to $VISUAL, then $EDITOR
previewer = "" # e.g. "katdown" or "glow -p"
journal_template = "# {{.Date}}\n\n"
date_format = "yyyy-mm-dd"
start_page = "none" # none, last, today, page/<id>…
theme = "auto" # follows the system / terminalChange them with katnotes config set <key> <value>, katnotes config edit, or the GUI's Settings dialog.
Install
Build with Go 1.26+ and go-task; the GUI also needs Node and the Wails v3 CLI (and GTK 3 / WebKitGTK 4.1 on Linux).
git clone https://github.com/devinthemtn/katnotes.git
cd katnotes
task install # installs katnotes and katnotes-guiOn Windows, run the KatNotes-<version>-windows-amd64-setup.exe installer (per user, no admin). Under WSL, task install also installs the Windows versions and points them at your WSL notes, so both share one set of notes.

