darshan

Darshan (दर्शन) is Sanskrit for "seeing": a view of something, taken in properly.

darshan opens in a tmux popup, inside your work. Close it and your file stays open, on the same page, until you say otherwise. Press one key and it fills the screen with nothing but the page. Ask an agent to show you a document and you can question it from right there: your question reaches the agent with the page you're on, and its answer shows beside the page.

#Features

• Real pages and pictures on kitty and Ghostty, inside tmux and its popups too; coloured blocks on other terminals. Markdown is drawn as styled text.
• Vim keys: j k h l, gg G, counts (5j, 12G), Ctrl+d/Ctrl+u, / with n/N, : for commands (a page number, q, bd, e FILE).
• Search the whole system: f finds any PDF, image or Markdown file by name, with a live preview of the one you're on. Recent files come first.
• The popup remembers: prefix v opens it and closes it. Your file and page come back until you close the file with x.
• Zen mode: z switches between the normal popup and the full screen with nothing but the page.
• Dark mode: i inverts pages and pictures, for reading at night.
• It follows the file: when a file changes, it reloads and keeps your page.
• AI agents: an MCP server lets any agent show you a file and talk about it.

#Install

curl -fsSL https://raw.githubusercontent.com/Theyashsawarkar/darshan/main/install.sh | bash

Or make install, or with TPM: set -g @plugin 'Theyashsawarkar/darshan', which binds prefix v. It needs poppler (pdftoppm, pdfinfo, pdftotext) for PDFs and fd for the search; darshan doctor checks. tmux needs set -g allow-passthrough on only for other tools: darshan writes straight to the client's terminal.

To make it the desktop's viewer, install packaging/darshan.desktop and xdg-mime default darshan.desktop application/pdf image/png image/jpeg. darshan open FILE shows a file in the running screen, a tmux popup, or from the desktop a kitty window of its own.

#Keys

Reading

Searching for a file

Talking to the agent

#AI agents

Add it once and every agent can use it:

claude mcp add darshan -- darshan mcp

Asking. When an agent opened the file, a opens the talk beside the page. Your question goes with the file, the page and the text on your screen: to the agent if it's waiting in view_next_question, else typed straight into its tmux pane, so it arrives like a message from you. If that pane has dropped to a shell darshan won't type there; the question waits until the agent next asks for it. The document's text is marked as data, so words inside a PDF can't pose as your instructions. If the agent regenerates the file, it reloads where you were.

#Options

~/.config/darshan/config.toml:

roots   = ["~/more-books"]   # folders to search, beside home, other disks and system docs
exclude = ["archive"]        # folder names to skip, beside node_modules, .git, .cache and the like

tmux options, before TPM's run line:

Colours follow varna when it's there.

#How it draws

PDF pages become PNGs through poppler's pdftoppm (cached in ~/.cache/darshan). They reach the terminal by kitty's graphics protocol, written to the tmux client's own terminal, and show through Unicode placeholders, which any text layout carries: that's why they work in popups, where viewers that draw directly (tdf, for one) show nothing.

Not yet: highlighting a match on a PDF page (/ jumps to the page), animated GIFs (the first frame shows), pictures inside Markdown.