No description
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Bruno Carlin 58f9f4a5d7
feat!: leave the program with :quit only
q quit the whole program from the listing, and it is too easy to type by
accident. The frame keymap no longer binds quit: :quit (or :q) is the only
way out, and ctrl+c now names that command alone. q still closes a memo,
an attachment, an image, the editor and the help panel.

The memo tab's q/esc close only led the help line because it took over the
frame's q. It now leads because it is close: a window's close action comes
right after the frame keys, or it falls past eighty columns. Window
keymaps spell it through closeAction, since that rule keys on the name.

BREAKING CHANGE: q no longer quits from the listing; type :quit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 16:43:51 +01:00
.claude/rules feat!: leave the program with :quit only 2026-11-15 16:43:51 +01:00
docs feat!: leave the program with :quit only 2026-11-15 16:43:51 +01:00
internal feat!: leave the program with :quit only 2026-11-15 16:43:51 +01:00
.gitignore refactor: rewrite calendar so it processes its own actions 2026-09-27 01:16:47 +02:00
.golangci.yml fix: bound the cost of rendering a memo or a markdown attachment 2026-11-08 23:34:03 +01:00
CLAUDE.md docs: add a README and user documentation for theme, keys and commands 2026-09-19 14:24:05 +02:00
go.mod fix: bound the cost of rendering a memo or a markdown attachment 2026-11-08 23:34:03 +01:00
go.sum feat: draw an image attachment in :view through kitty graphics 2026-11-08 14:48:18 +01:00
main.go feat: make every icon configurable under [theme.icons] 2026-11-08 23:34:07 +01:00
main_test.go feat: open, download and view a memo's attachments from its tab 2026-11-07 15:49:39 +01:00
README.md feat!: leave the program with :quit only 2026-11-15 16:43:51 +01:00

memos-tui

A terminal client for Memos, written in Go with Bubble Tea.

It opens on the memos of one account: a listing on the left, a sidebar holding a contribution calendar and the tag tree on the right, and an optional preview of the memo under the cursor. Keys are vim-flavoured, and every one of them is also a typed command.

Features

  • Paginated listing, fetching the next page before the cursor reaches the end.
  • Sidebar with a calendar heatmap and a folding tag tree, both of which filter the listing.
  • Preview of the memo under the cursor, beside the listing or under it.
  • Memos opened in tabs of their own, rendered as markdown, with their attachments listed under them: opened with the desktop's own program, downloaded, or read in a tab when they are text.
  • Memos edited in place — content, visibility, Space and creation date — and written back to the instance, with what has not been saved refusing to be thrown away.
  • First-run setup form: no configuration file has to be written by hand.
  • Credentials obtained from an external command, so no token need be stored in clear.
  • Fully themable interface — 70 named elements — with a NO_COLOR escape hatch.

Requirements

  • Go 1.26 or later to build.
  • A Memos instance — 0.30, 0.31, 26.10 or 26.11 — and a personal access token for it (memos_pat_…). Which API the instance speaks is asked of it on every connection, so an upgrade needs no change here.
  • xdg-open, to open an attachment with the desktop's own program.
  • Optionally, a truecolor terminal speaking the kitty graphics protocol, to draw an image attachment in a tab. The terminal is asked, not guessed.

Installation

From a clone:

go build -o memos-tui .

Or, where the module proxy can reach the repository:

go install code.bcarlin.net/labs/memos-tui@latest

First run

Started with no configuration, the program shows a setup form asking for a name, the instance address, an optional user, and a credential. Once the instance accepts it, the configuration file is written and the listing opens.

Nothing is written before the instance has answered, so a configuration that never worked is never saved.

Configuration

The file lives at $XDG_CONFIG_HOME/memos-tui/config.toml, which is ~/.config/memos-tui/config.toml unless the variable says otherwise. It is created 0600, in a directory created 0700.

download_dir = '~/Downloads'

[[servers]]
name = 'perso'
address = 'https://memos.example.net'
user = 'alice'
token_cmd = ['secret-tool', 'lookup', 'service', 'memos']

token_cmd is an argv — it is executed directly, never through a shell — and is preferred over token, which stores the credential in clear in the file. The argv itself is not a secret: it is stored in clear like any other value, and it is visible in the process table while the command runs, so nothing secret belongs in its arguments.

The program resolves the command once and reuses what it got. A refusal from the instance, or a prompt that failed, drops what was held — the next fetch then resolves again. :reauth re-runs it whatever is held.

Each server has a listing of its own, one tab per [[servers]] entry in the order of the file. Only the first is fetched at start; another is fetched the first time gt or gT reaches it, which is when its token_cmd runs. Two server names that would share a directory on disk — a/b and a_b, .x and x — are refused, like two equal names.

download_dir is where :download writes when it is given no path. Left out, it is XDG_DOWNLOAD_DIR — from the environment or from user-dirs.dirs, as xdg-user-dirs writes it — and then ~/Downloads. It is a top-level key, and stays above every [section]: written under one, TOML files it there, and it is silently ignored.

memos-tui --init-config writes a commented file listing every theme setting. It never touches an existing one.

The program rewrites this file whenever it saves a server, and the rewrite keeps values only: comments are lost, along with any key this version does not know about.

Theming is documented in docs/theme.md.

Usage

memos-tui [options]

  -init-config
        write a commented configuration file, then exit
  -print-theme
        list every element of the interface in its style, then exit

If a theme ever leaves the interface unreadable, NO_COLOR=1 memos-tui draws everything as plain text, whatever the configuration says.

Press ? for the available commands, : to type one, and :quit to leave. o opens the memo under the cursor in a tab and e edits it, where q closes that tab; gt and gT walk the tabs.

Documentation

Development

go test ./...
golangci-lint run

Tests are written first; the conventions and the traps this codebase has run into are recorded under .claude/rules/.

License

None declared yet.