tmr: terminal markdown reader

A two-column file explorer for the terminal. The files in the current folder are listed on the left. Click a markdown file, or move onto it with the arrow keys, to read it, formatted, on the right. Made for reading (and lightly editing) the documents agents write: it follows changes on disk, finds files and words quickly, copies as markdown, ticks checkboxes, and commits one file to git.

Works on macOS and Linux (Python 3.13 or later). This is version 1 (1.0.2; tmr --version says which you have).

Install

uv tool install terminal-markdown-reader   # or: pipx install terminal-markdown-reader

Start it

cd some/folder
tmr                       # browse this folder
tmr docs/plan.md          # open a specific file straight away
tmr docs/plan.md#setup    # ...at its "Setup" heading
cat notes.md | tmr        # read markdown piped in
tmr --all --hidden        # list every file, hidden and ignored ones too
tmr --help                # every option (--no-watch, --colors, --font-size)

Keys

Good to know

• Everything works with the mouse too: click files, links and the hints at the bottom, and drag the bar between the columns to resize the file list. Clicking a task's box ticks it in the file itself, and highlighting text copies it to the clipboard as markdown.
• The file list leaves out hidden files and whatever git ignores, apart from markdown: notes in an ignored folder (drafts/) are still listed. Press . to show everything.
• The top right shows about how many tokens the file is (~12k tokens, at four characters to a token), to see whether it's getting big for an agent to read.
• If something else (an agent, say) changes a file while you edit it, saving keeps both your edits and theirs. If both changed the same lines, nothing is saved yet: the two versions are shown between <<<<<<< your edits and >>>>>>> changes on disk for you to sort out and save again.
• macOS Terminal starts out with a small font, so there tmr sets its tab to 15 points while it runs and puts your size back when you quit.

Settings

Development

uv run pytest                 # run the tests
uv run ruff check src tests   # lint
uv tool install --editable .  # install the `tmr` command from this checkout

Built with Textual (layout, markdown), textual-image (pictures) and termaid (mermaid diagrams).

Textual is pinned to one minor version (textual>=8.2.8,<8.3): tmr reaches into a few of its internals (the directory tree's rows, the text area's highlighting, the terminal driver's mouse modes, the notifications list) to draw things its own way. A newer Textual may well work, but each bump is checked against the tests before the pin moves.

Contributions are welcome: see CONTRIBUTING.md. What changed in each version is in CHANGELOG.md.

MIT licence: see LICENSE.