Dev In The Mountain Header
A Developer In The mountains having fun

katNotes

← The kat Suite · GitHub

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: :sync commits 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:

sh
rg 'due:2026-11' ~/KatNotes        # due this month
rg '\{[^}]*pri:high' ~/KatNotes     # high priority

CLI

bash
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, push

Every command accepts --json for scripting.

TUI keys

KeyAction
j / k, gg / Gmove, first / last
tab, 1–4Pages, Journal, Tags, Tasks
nnew note
enter / eedit in your editor
ppreview (katdown, glow…)
Jtoday's journal
/, ctrl+psearch, quick open
T, Ledit tags, link to another note
gb / gfbacklinks / links
x, @, ptasks: 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, [[fri work too)
  • Type / for commands like /todo, /due, /pri, /today, /time, plus your own Lua ones
  • Ctrl+Enter makes a line a task or checks it; { on a task line suggests keys and values
  • Ctrl+Shift+T shows every task from every note
  • Ctrl+Shift+Z hides the sidebar and top bar for focus
  • A Settings dialog covers every option

Lua commands

lua
-- ~/.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

toml
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 / terminal

Change 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).

bash
git clone https://github.com/devinthemtn/katnotes.git
cd katnotes
task install        # installs katnotes and katnotes-gui

On 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.

More places to find me
Mental Health
follow me on Mastodon