⌂ house

A terminal markdown reader and navigator — themable and configurable, with a keyboard-driven modern UI. Browse a directory of .md files without leaving the terminal.

Features

• 30+ themes with dark and light tones
• Responsive layout
• Fuzzy search across nested folders (.gitignore-aware)
• Command palette
• Keyboard-driven
• Open in browser
• Open in $EDITOR

Requires Bun on PATH.

Runtime requirements

• Bun: required to install and run house today.
• npm can install the package, but npm evaluates Node engine metadata from transitive dependencies during install. Use bun add -g for the supported no-Node install path.

Supported on macOS and Linux; Windows is unsupported and unvalidated (see #129).

Install

bun add -g @carlesandres/house
# npm also works when your local Node/npm combination accepts the dependency graph:
npm install -g @carlesandres/house

Upgrade

bun add -g @carlesandres/house
# npm also works when your local Node/npm combination accepts the dependency graph:
npm i -g @carlesandres/house

Usage

house [query] [options]

By default, house opens the browser over the configured discovery root: the current directory, or the git root when defaultRoot = "git" is configured. Use --root <dir> to browse a specific directory.

[query] seeds the initial sidebar filter query. It can be a filename, a relative path, or any path fragment you want to match. It does not set the discovery root; use --root <dir> for that.

Examples:

house                  # browse the configured discovery root
house README.md        # browse with README.md preloaded as the sidebar filter
house --root docs      # browse docs/ as the discovery root
house --serve README.md

Options

| Flag | Default | Description | | -------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------ | | --theme <name> | opencode | Starting theme (see list below) | | --tone dark\|light | dark | Starting tone | | --width <N> | 80 | Reader wrap width used when wrapping is enabled | | --wrap | off | Start with reader wrapping enabled | | --no-wrap | off | Start with reader wrapping disabled | | --show <list> | "" | Reveal normally-skipped entries; comma-separated subset of hidden, gitignored. Use --show "" to clear. | | --root <dir> | current directory | Discovery root to walk; overrides defaultRoot config/env | | --focus <mode> | sidebar | Startup focus: sidebar, reader, or filter. filter opens the sidebar filter prompt immediately. | | --serve | off | Serve the positional path as HTML in the browser (skips TUI) | | --port <N> | OS-assigned | Port for --serve | | --ext <list> | none | Include extra file extensions (comma-separated) | | --no-update-check | off | Suppress the "newer version available" check (also via NO_UPDATE_NOTIFIER=1) | | --config-path | — | Print the resolved config-file path and exit | | -h, --help | — | Show help and exit | | -v, --version | — | Print version and exit |

Configuration

house reads optional defaults from a TOML file:

$XDG_CONFIG_HOME/house/config.toml   (defaults to ~/.config/house/config.toml)

Run house --config-path to print the exact location.

# ~/.config/house/config.toml
theme = "tokyonight"
tone  = "dark"
extensions = []
width = 80
wrap = false
show  = ["hidden", "gitignored"]
focus = "sidebar"
defaultRoot = "cwd" # or "git"

Supported keys: theme, tone, extensions, width, wrap, show, focus, defaultRoot.

show is a list of normally-skipped categories to opt into. Known categories: hidden (dot-prefixed entries), gitignored (entries matched by a .gitignore). Default is the empty list. Hard skips (node_modules, .git, .venv) always apply.

Precedence, highest to lowest:

1. CLI flags (--theme, --tone, --ext, --width, --wrap, --no-wrap, --show, --focus, --root)
2. Env vars (HOUSE_THEME, HOUSE_TONE, HOUSE_EXTENSIONS, HOUSE_WIDTH, HOUSE_WRAP, HOUSE_SHOW, HOUSE_FOCUS, HOUSE_DEFAULT_ROOT)
3. Config file
4. Built-in defaults (opencode / dark / extensions = [] / width = 80 / wrap = false / show = [] / focus = "sidebar" / defaultRoot = "cwd")

HOUSE_SHOW takes a comma-separated list (HOUSE_SHOW=hidden,gitignored). For show specifically, each source completely replaces the next — categories don't merge across layers. Press shift+a in the TUI to round-trip between the configured set and the full vocabulary without editing config.

width is the fixed reader width used when wrapping is enabled. wrap controls startup mode; press w in the TUI to toggle reader wrapping for the current session without editing config.

The file is optional — a missing file is fine. Invalid keys, unknown themes, or malformed TOML fail loudly with a one-line error. Per-project config (.house/config.toml) and additional keys are deferred.

Keys

Global

| Key | Action | | -------------- | ----------------------------------------------------------- | | q / ctrl+c | Quit | | tab | Toggle focus (sidebar ↔ reader) | | s | Toggle sidebar visibility | | ctrl+p | Command palette | | w | Toggle reader wrap | | O | Open current file in browser as HTML | | E | Open current file in $EDITOR ($VISUAL takes precedence) | | t | Next theme | | T | Previous theme | | L | Toggle dark / light tone |

Sidebar

| Key | Action | | ------------------------------- | ----------------------------------------------------------------------------------------- | | j / ↓ | Move selection down | | k / ↑ | Move selection up | | J | Jump down 8 | | K | Jump up 8 | | space / pagedown / ctrl+d | Page down | | b / pageup / ctrl+u | Page up | | g | First file | | G | Last file | | / | Filter files (fuzzy match on path) | | A | Toggle hidden + gitignored entries (session-only; round-trips with the configured show) | | ↵ / → / l | Open file (focus reader) |

Reader

| Key | Action | | ----------------- | --------------- | | esc / ← / h | Back to sidebar | | [ | Previous file | | ] | Next file |

Themes

33 built-in themes, all sourced from the opencode TUI palette:

aura · ayu · carbonfox · catppuccin · catppuccin-frappe · catppuccin-macchiato · cobalt2 · cursor · dracula · everforest · flexoki · github · gruvbox · kanagawa · lucent-orng · material · matrix · mercury · monokai · nightowl · nord · one-dark · opencode · orng · osaka-jade · palenight · rosepine · solarized · synthwave84 · tokyonight · vercel · vesper · zenburn

Each theme supports dark and light tones. Cycle with t / T; toggle tone with L.

For the supported semantic theme tokens and their intended usage, see DESIGN.md §7.5.

Inspiration

• glow — render markdown on the CLI, with pizzazz
• ghui — keyboard-driven terminal UI for GitHub pull requests
• hunk — review-first terminal diff viewer for agent-authored changesets
• opencode — terminal UI whose palette inspired house's themes

License

MIT