brothy

A calm terminal Markdown reader for a folder of notes.

Point brothy at a folder and read. ctrl+p jumps to any note, heading or line, zen hides everything but the text, and the note reloads when you save it somewhere else. It reads Obsidian vaults as they are and comes with 42 themes. AI is optional and runs only when you press a key.

Documentation · Play the tour · Keys · Changelog

Install

macOS or Linux, in a terminal with true color and Unicode. Download brothy-<os>-<arch> (linux or darwin, x64 or arm64) and SHA256SUMS from the releases page, then:

sha256sum -c --ignore-missing SHA256SUMS     # shasum -a 256 -c on macOS
chmod +x brothy-linux-x64
mv brothy-linux-x64 ~/.local/bin/brothy        # any folder on your PATH

On macOS you may need to clear the quarantine flag first: xattr -d com.apple.quarantine brothy-darwin-arm64.

On Arch Linux, brothy-bin in the AUR installs the same binary (kept by a community packager): yay -S brothy-bin.

Build from source

Needs Bun 1.4 or newer. brothy is not published to npm.

git clone https://github.com/jackMort/brothy.git && cd brothy
bun install
bun run build                # single binary ./brothy, parsers embedded

Quick start

brothy                # browse the current folder
brothy ~/notes        # browse a folder
brothy README.md      # open one file (its folder fills the panel)
brothy -t dracula     # pick a theme
curl -s … | brothy    # read a pipe

Press ? for hints and ? twice for every key. ctrl+p goes anywhere, t picks a theme, z starts zen and q quits.

What it does

• Renders headings, tables that shrink to fit, highlighted code and task lists at a readable 80 columns, with s for the Markdown source. Reading
• Reads Obsidian notes as they are: wikilinks, embeds, callouts, ==highlights==, %%comments%%, properties and dataview blocks. Obsidian notes
• Finds things fast: ctrl+p over every note, heading and line with a preview, f to follow a link by its label, H and L for back and forward. Navigating notes
• Draws the open note's links (ctrl+g): the notes it links to and from, out to two links, in pixels where the terminal shows images and in braille elsewhere. Graph view
• Shows pictures (![alt](img.png), ![[img.png]]) in the note where the terminal draws images and as a row elsewhere; ⏎ views one larger. Pictures
• Reloads when the file changes on disk and numbers the sections that changed.
• Leaves only the text in zen (z): scroll or pages, spotlight, typewriter or teleprompter. Zen mode
• Ships 42 themes in 22 families, picked on a board with a live sample (t). Themes

AI, off by default

Note

Nothing is sent until you add an ai block to ~/.config/brothy/config.json and press one of the keys below. Requests go only to the endpoint you configured, and brothy makes no other network requests. API keys are read from the environment, never from the config file.

A local model needs no key:

"ai": { "provider": "ollama", "model": "llama3.2" }

• a summarizes the note and keeps the result. TL;DR
• a in zen explains the section you are reading in a sentence or two. Zen gloss
• D explains what changed in the file since you opened it. What changed
• ? in ctrl+p asks a question. The model only suggests search words and brothy finds the sections itself. Ask your vault

It also works with LM Studio, OpenAI, OpenRouter, Anthropic, Gemini and any OpenAI-compatible server. Set up a provider · What is sent · SECURITY.md

Alternatives

glow (pager and note stash), mdcat (renders to stdout), frogmouth (Python TUI browser), bat (syntax-highlighted cat) and Obsidian itself. brothy is a reader for a folder of notes, not an editor.

Contributing

bun install
bun run dev          # run against ./examples
bun test

CLAUDE.md explains how the code is laid out. See CONTRIBUTING.md, the Code of Conduct and CHANGELOG.md; report security problems privately as described in SECURITY.md.

Support

brothy is free. If it earns a place in your terminal, you can buy me a coffee.

Credits

The look comes from Noodle, and brothy is built the same way: Bun, TypeScript, React and OpenTUI. The brothy themes follow Noodle's theme definitions (Apache-2.0). Additional palettes are adapted from opencode (MIT, © 2025 opencode), and ayu, nightfox, Night Owl, iceberg, oxocarbon, cyberdream, melange, SynthWave '84 and Vesper from their own repositories (all MIT; see NOTICE), all tuned for contrast; brothy-light is original.

License

Apache-2.0; see NOTICE for attributions.