📖 tome

Read any repo's markdown in a browser tab. One Python file, zero dependencies, no build step, no network.

cd ~/work/some-repo
tome --open

That's it. tome finds the repo root, discovers every .md under it, groups them the way the repo is actually laid out, and serves a fast reader on 127.0.0.1. Edit a doc in your editor and the page re-renders in place, keeping your scroll position.

It exists because reading docs inside the editor is bad — you lose the split you were coding in, the rendering is mediocre, and cross-doc links go nowhere. Docs belong in the other window.

What it looks like

⌘K searches every doc at once — fuzzy title matches first, then full-text hits with the matching line and its line number. Enter jumps you to the match, not just the page.

Links into code actually open the code. A doc that says [error.rs](../src/error.rs) gets you the real file, syntax-highlighted, in the same reader — no editor round-trip to check whether the doc still matches reality.

Nineteen themes, hover to preview. Each swatch is rendered in its own palette, so what you hover is what you get. The choice follows you into every other repo you open.

_{Screenshots are of backend-gauntlet, a 22-package monorepo — the sidebar grouping and status dots come from its layout, not from configuration.}

Why not just use the GitHub preview / a static site generator?

tome is not a documentation site generator. It never produces a build artifact, and it is not for publishing. It's a reader for the docs you already have, on your machine, right now.

Install

Pick whichever matches how you already install tools.

# uv — recommended, installs the `tome` command globally
uv tool install tome-docs

# pipx
pipx install tome-docs

# plain pip
pip install tome-docs

# no install at all — run it straight from PyPI
uvx --from tome-docs tome

Want the tip of main instead of the latest release? Point any of the above at the repo:

uv tool install git+https://github.com/utkarsh5026/tome

Or, because it really is one file with no imports beyond the standard library:

curl -o ~/.local/bin/tome https://raw.githubusercontent.com/utkarsh5026/tome/main/tome.py
chmod +x ~/.local/bin/tome

Needs Python 3.9+. That's the entire dependency list.

No Python? Download a binary

Every release also ships a standalone executable with the interpreter baked in — one file, nothing to install, no Python anywhere on the machine.

Pick your platform — each link downloads the newest build directly:

On Windows, double-clicking works — it serves whatever folder it sits in.

# macOS / Linux — make it executable and put it on PATH
chmod +x tome-macos-arm64
mv tome-macos-arm64 ~/.local/bin/tome

The binaries are unsigned, so the OS will say so the first time: on macOS, right-click → Open once (or xattr -d com.apple.quarantine tome); on Windows, SmartScreen's More info → Run anyway. Checksums for every file live in SHA256SUMS, and the release page has the rest.

Worth knowing what you're trading: the binary is ~10 MB against the source's 100 KB, because most of it is Python itself. If you already have an interpreter, the installs above are the better deal.

Update

Whichever way you installed it, updating uses the same tool — tome doesn't phone home or update itself:

uv tool upgrade tome-docs      # uv
pipx upgrade tome-docs         # pipx
pip install -U tome-docs       # plain pip

# installed from the tip of main
uv tool install --force git+https://github.com/utkarsh5026/tome

# installed via curl
curl -o ~/.local/bin/tome https://raw.githubusercontent.com/utkarsh5026/tome/main/tome.py

tome --version prints what you currently have.

Use

tome                      # serve the repo you're standing in
tome --open               # …and open a browser tab
tome --port 9000          # preferred port (auto-advances if taken)
tome README.md            # open straight to a file
tome docs/adr             # …or a directory (opens its README/SPEC)
tome 10                   # …or a numbered package: projects/10-*
tome --root ~/work/api    # serve a repo you're not standing in

Run it in several repos at once — the port auto-advances, and each repo remembers its own reading position independently.

Keys

What it renders

A focused GFM subset, chosen by looking at what real repo docs actually contain:

• headings with anchor links and a live table of contents
• fenced code with syntax highlighting for Rust, Python, TypeScript, Go, SQL, bash, JSON, TOML, YAML, Dockerfile, Makefile — hand-rolled, ~60 lines, no Pygments
• GFM tables with alignment, task lists, nested lists, blockquotes
• GitHub alert callouts (> [!NOTE], > [!WARNING], …)
• images, mermaid blocks, and a whitelist of inline HTML
• links that resolve: [router.rs](../src/router.rs) opens the real source file, syntax-highlighted, inside the reader. Broken links render in red, so a doc that's drifted from the code is visible at a glance.

Configuration

There is none, until you want some. Drop a .tome.json at the repo root:

tome --init-config

{
  "title": "backend-gauntlet",
  "icon": "🦀",
  "pinned": ["SPEC", "CONCEPTS", "RESEARCH", "README"],
  "groupDirs": ["projects", "packages", "crates"],
  "skip": ["fixtures", "snapshots"],
  "theme": "tokyo",
  "home": "README.md",
  "editor": "vscode"
}

How grouping works

Three rules, applied in order:

1. Markdown at the repo root becomes one repo section.
2. A directory listed in groupDirs contributes one section per child — so projects/10-api-gateway/ becomes its own section, labelled 10 · api gateway. This is the monorepo case.
3. Every other top-level directory is a single section.

A leading NN- on a package name is pulled out and shown as its number, which is also what makes tome 10 work.

Status dots

Optional, and inert if you don't use it. If a section's SPEC.md, STATUS.md, or README.md opens with a render-invisible status block, the sidebar shows a coloured dot for it:

<!-- status:
state: active            # active | paused | blocked | done | not-started
-->

Notes on the design

• One file, standard library only. Not a constraint for its own sake: it means tome installs in one second, runs on any machine with Python, and can be vendored into a repo by copying a single file. The markdown parser, the syntax highlighter, and the HTTP server are all in there and all deliberately small.
• The markdown parser is not CommonMark and doesn't try to be. It handles what repo docs use. When it meets something it doesn't know, it degrades to a paragraph rather than mangling the page.
• The syntax highlighter is a tokenizer, not a parser. Good enough to read at a glance; it will get an edge case wrong and that's an accepted trade.
• Loopback only. It serves file contents out of your repo. It binds 127.0.0.1 and refuses to serve .env files, private keys, .netrc, and friends — but it is a local reader, not a server to expose.
• Preferences are global, position is per-repo. Your theme follows you across every repo; "the doc I was last reading" doesn't.

License

MIT © Utkarsh Priyadarshi