⌂ 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

Install with npm or Bun. Prebuilt binaries cover macOS and Linux (arm64/x64); no Bun required to run on those platforms.

Runtime requirements

• Run: a prebuilt binary for your platform (pulled in automatically on install). No Bun needed at runtime on supported platforms.
• Install: Node/npm or Bun both work. Prefer npm install -g for the normal end-user path.

Supported on macOS and Linux (arm64/x64, glibc Linux). Windows is unsupported and unvalidated (see #129).

Install

npm install -g @carlesandres/house
# or:
bun add -g @carlesandres/house

Upgrade

npm i -g @carlesandres/house
# or:
bun add -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 --order tree     # files-before-directories instead of recency
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. | | --order <mode> | recently-modified | File Navigator browse order when the filter is empty: tree or recently-modified. | | --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"
order = "recently-modified" # or "tree"

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

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, --order, --root)
2. Env vars (HOUSE_THEME, HOUSE_TONE, HOUSE_EXTENSIONS, HOUSE_WIDTH, HOUSE_WRAP, HOUSE_SHOW, HOUSE_FOCUS, HOUSE_DEFAULT_ROOT, HOUSE_ORDER)
3. Config file
4. Built-in defaults (opencode / dark / extensions = [] / width = 80 / wrap = false / show = [] / focus = "sidebar" / defaultRoot = "cwd" / order = "recently-modified")

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.

order is the File Navigator browse order when no filter query is active. recently-modified (default) lists the most recently updated files first, using filesystem modification time, then tree order for ties. tree lists files before directories, alphabetically within each group, so current-directory files appear before nested subtrees. An active filter still ranks by relevance first.

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

Keys

The footer only shows essential app controls (W, q, tab, s, ctrl+p) to stay quiet. Use the command palette for the rest.

Global

| Key | Action | | -------------- | ----------------------------------------------------------- | | q / ctrl+c | Quit | | tab | Toggle focus (sidebar ↔ reader) | | s | Toggle sidebar visibility | | ctrl+p / ? | Command palette (? does not fire while typing in filter, palette, or name prompts) | | w | Toggle reader wrap | | O | Open current file in browser as HTML | | E | Open current file in $EDITOR ($VISUAL takes precedence) | | N | Prompt for a name, create an empty markdown file at the discovery root, then open it in $EDITOR | | R | Rename the selected file's basename (same folder; does not move) | | 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