peruse

A lightweight web server for calmly reading a local directory in your browser: directory tree on the left, beautifully rendered file on the right.

• GOOD markdown rendering — GitHub-flavored, with code fences highlighted exactly like standalone code files
• GOOD code rendering — Shiki (VS Code–quality TextMate highlighting), including mdsvex .svx source files
• Git-aware — status marks in the tree with a changed-only filter, plus the current branch and its ahead/behind state in the header
• Inline hunk diffs — subtle gutter marks show where a file changed; click one to expand that individual hunk's diff in place. Never a whole-page diff view.
• Live — watches the directory and keeps open views up to date as files change on disk
• Catppuccin — Latte (light) and Mocha (dark), following your system preference with a manual toggle
• Built for reading and review — word wrap for long lines, one-click copy of a file's exact source, browser tabs titled by server and project, and a version indicator that distinguishes releases from dev checkouts

See ARCHITECTURE.md for the system as implemented, CHANGELOG.md for release history, and docs/design-history.md for the original design and the survey of existing tools.

Usage

cd some/directory
bunx @talkasab/peruse .      # registers this directory and prints its project URL

Requires Bun 1.4.0 or newer.

peruse [path] [--port 7440] [--host 127.0.0.1]
peruse add <path> | rm <name-or-path> | list | prune

peruse prints URLs and never opens a browser — its home use case is browsing a remote machine's files (SSH into the box, click the printed link locally).

Opened paths are remembered in ~/.config/peruse/projects.json. Running peruse without a path opens a landing page for all registered projects; each project has a shareable /p/<name>/ URL and linked Git worktrees appear under it automatically. Missing paths stay visible for 30 days unless removed with peruse prune.

If the default port is busy, peruse walks forward to the next free one (7441, 7442, …). A port given explicitly with --port is used as-is, or fails if taken.

peruse is read-only with respect to every directory it serves. Its only persistent application data is the project registry under ~/.config/peruse/, and it binds to localhost only by default.

Showing ignored paths

Add .peruseshow to a project's served root to browse selected paths that Git ignores. For example:

# .peruseshow
docs/generated/
.agents/scratch/
build/reports/*.html

Use one pattern per line. Blank lines and lines beginning with # are ignored. A leading or internal / anchors a pattern to the served root. A trailing / selects directories. Names without a leading or internal slash can match at any depth. * and ** follow Bun's glob rules. Leading spaces are part of a pattern. Negation is unsupported. To open an ignored directory, name it or a descendant through complete, literal directory segments. A bare file glob such as *.local.md matches files only in directories the tree already walks. Matched directories and their files remain dimmed and respond to hide ignored. Peruse reads the file again on the next tree refresh, so edits take effect while the server runs. This file applies only to that project.

Browsing from other machines (LAN / Tailscale)

peruse --host 0.0.0.0          # bind all interfaces; prints every reachable URL
peruse --host 100.64.12.34     # or bind only your Tailscale address

With 0.0.0.0, peruse lists each address a browser could reach it at (LAN IP, Tailscale IP, …). Binding just the Tailscale IP keeps it off the local network entirely; alternatively keep the localhost default and front it with tailscale serve 7440.

Caveat: peruse has no authentication — anyone who can reach the port can read the entire served directory. Symlinks are followed, including ones that point outside the served directory — so what's reachable is the directory plus everything it links to. Only expose directories you'd share with everyone on that network. (Opt-in symlink confinement for network mode is tracked in issue #21.)

Design at a glance

A multi-root Bun server (Bun.serve, native fs.watch) plus a single static client that composes markdown-it, Shiki, diff2html, and Alpine.js, bundled at publish time with bun build. Watchers are created lazily for projects that are actually opened. The current system is described in ARCHITECTURE.md; the original reasoning is preserved in docs/design-history.md.

Development

bun install
bun run bin/peruse.js <path>     # the server auto-builds dist/ when web/ is newer

The CLI retains its low-fd ulimit -n re-exec pending macOS verification of the native watcher.

License

MIT