⚠️ This project was entirely 'vibe coded' and was done as an experiment. Does it work? Yes, just as it's meant to actually. Is it a little rough around the edges? Oh my yes. There's plenty that could be done to polish this thing, and I may well return to it if/when I ever decide that I'm ok with being part of the agent's workflow, rather than the agent being part of my workflow...so maybe never.

doc_scrolls

Terminal-first docs browser with offline search and markdown rendering.

V1 Scope

• Source support: Python docs only
• Install docs locally and index with SQLite FTS5
• Textual TUI with a single content pane and a slash-command prompt
• Vim-style navigation

Install

cd ~/github/Linux-Alchemy/doc_scrolls
python -m venv .venv
source .venv/bin/activate
pip install -e .

Or with uv:

UV_CACHE_DIR=.uv-cache uv sync --extra dev

Usage

# install Python docs (default docs.python.org/3)
doc-scrolls install python

# list installed docsets
doc-scrolls list

# search from CLI
doc-scrolls search "asyncio gather"

# open terminal UI
doc-scrolls open python

CLI Commands

Command	Description
doc-scrolls install python	Download and index Python docs locally
doc-scrolls install python --version 3.12	Install a specific version
doc-scrolls list	Show all installed docsets
doc-scrolls search "query"	Search from the command line
doc-scrolls search "query" --limit 5	Limit number of results
doc-scrolls open python	Launch the TUI browser

TUI

The TUI has a single content area and a prompt docked at the bottom. The prompt works in two modes:

• input — the prompt is focused; typing queries or slash-commands
• nav — the content area is focused; vim keys scroll/select

Slash Commands

Type in the prompt and press Enter.

Command	Description
/	Show the command list
/list	Show installed docsets
/toc	Table of contents for the current doc
/find <term>	Find a term in the current doc
/home	Return to the welcome screen
/help	Keybinding reference
/q or /quit	Quit

Anything that doesn't start with / is treated as a search query.

Keybindings

Key	Mode	Action
/	nav	Jump to the prompt
Escape	input	Switch to nav mode
Escape	nav	Go back (doc → results → welcome)
Enter	input	Run search / slash command
Enter	nav	Open the highlighted result or ToC entry
j / k	nav	Scroll down/up, or move selection
d / u	nav	Half page down/up
g / G	nav	Jump to top/bottom
PgUp / PgDn	nav	Page up/down
n / N	nav	Next / previous find match
q	nav	Quit
Ctrl+Q	any	Quit

Example Workflow

1. Launch:          doc-scrolls open python
2. Search:          type "turtle" in the prompt, Enter
3. Pick a result:   Escape → j/k to highlight → Enter to open
4. Jump to section: /toc → Enter → j/k → Enter
5. Find keyword:    /find forward → Enter
6. Hop matches:     Escape → n / N
7. New search:      / to refocus the prompt, type a new query
8. Quit:            q (from nav) or Ctrl+Q

Theming

The TUI ships a custom terminal theme built entirely on ansi_* colours, so the app inherits whatever palette your terminal is using (Ghostty, Kitty, Alacritty, etc.) with zero config. No hex colours, no tone-mapping.

Notes

• First install requires internet. Search and browsing are offline after that.
• Clicking links in the doc pane navigates internally: anchors scroll to headings, page links load from the index.
• Adapter architecture is set up for adding more sources in V2.