Gorae

A terminal-first knowledge base for PDFs, EPUBs, and Markdown — with a built-in AI assistant that talks to your library.

Why Gorae

• Lives in your terminal. Vim-style browsing, mouse support, no Electron, no browser tab.
• AI assistant that knows your library. Chat, summarize, and RAG-Q&A directly against your indexed documents.
• Open and local-first. Your files, your metadata store, your choice of model (Ollama, OpenAI, anything OpenAI-compatible).

Like Obsidian + Zotero, but in your terminal — and Vim-friendly.

Quickstart

1. Download the binary for your platform from the latest release:
   • Linux: gorae-linux-amd64
   • macOS (Apple Silicon): gorae-darwin-arm64
   • macOS (Intel): gorae-darwin-amd64
   • Windows: gorae-windows-amd64.exe
2. Rename it to gorae, make it executable, and move it onto your PATH:

   mv gorae-linux-amd64 gorae                 # use the file you downloaded
   chmod +x gorae && mv gorae ~/.local/bin/   # or /usr/local/bin

3. Run it:

   gorae

4. Index your library so the AI assistant has something to read:

   :index
   

5. Open the chat:

   :gorae
   

Prefer building from source or using a package manager? See Install below.

Features at a glance

Area	What you get
Browsing	Vim-style nav, to-read queue, reading states, hierarchical tags (ml/cnn)
Search	FTS5 full-text index with stemming; scope by -t/-a/-y/-c/--tag; every hit in a document, jump between them, open at the hit's page
Preview	First-page PDF previews on Kitty / iTerm2; chafa fallback elsewhere
Metadata	Auto-detect DOI / arXiv IDs, in-app editor, BibTeX copy
Links	[[wikilinks]] in Markdown with auto backlinks
AI chat	RAG against your library, streaming responses, sessions, skills
AI tools	Model can invoke in-app actions like save_markdown (optional)
UI	Themeable colors, glyphs, borders; mouse + Vim modal navigation

AI Chat (:gorae)

A built-in RAG chat assistant grounded in your indexed library. Responses stream in real time.

:gorae         open the chat
:index         build the FTS index first so the assistant has context

Headline features:

• RAG out of the box — relevant chunks are retrieved from your library and injected into every query.
• Sessions — conversations are auto-saved; resume with /sessions, fork with /new.
• /load <query> — fzf-style live picker pins a file as primary context for follow-up questions.
• Vim-style navigation mode — Esc switches from typing to a message cursor: j/k between messages, Space to mark, y to yank one or many to the clipboard.
• Tool calling — with enable_tools: true, the model can invoke in-app actions like save_markdown to write summaries straight to notes_dir.
• Reasoning display — collapsible <think> blocks for DeepSeek-R1 / Qwen3 / QwQ.
• Web search — optional Brave / Tavily routing with a hybrid rules + LLM classifier.
• Skills — custom prompt templates as .md files become slash commands.

Minimal AI config — drop into config.json via :config

"ai": {
  "provider": "ollama",       // "openai" | "ollama" | "custom"
  "model": "llama3.2",
  "api_key": "",              // required for OpenAI / custom
  "base_url": "",             // override endpoint
  "top_k": 3,                 // chunks injected per query
  "system_prompt": "",
  "enable_tools": false       // let the model call in-app tools
}

Field	Description
provider	"openai", "ollama", or "custom"
model	e.g. gpt-4o, llama3.2, mistral
api_key	Required for OpenAI / custom. Empty for Ollama.
base_url	Defaults: OpenAI → https://api.openai.com/v1, Ollama → http://localhost:11434/v1
top_k	Document chunks injected per query (default 3)
system_prompt	Extra instruction prepended before RAG context
enable_tools	Allow tool calls (e.g. save_markdown). Default false.

Provider examples — Ollama, OpenAI, OpenAI-compatible

// Ollama (local — no API key needed)
"ai": { "provider": "ollama", "model": "llama3.2" }

// OpenAI
"ai": { "provider": "openai", "model": "gpt-4o-mini", "api_key": "sk-..." }

// Any OpenAI-compatible endpoint (Together, Groq, OpenRouter, …)
"ai": {
  "provider": "custom",
  "base_url": "https://api.together.xyz/v1",
  "model":    "meta-llama/Llama-3-8b-chat-hf",
  "api_key":  "..."
}

Pull the local model first if you haven't: ollama pull llama3.2. Good picks for document Q&A: llama3.2, mistral, gemma3.

Keyboard reference — insert mode + navigation mode

Insert mode (default — typing flows into the prompt):

Key	Action
Enter	Send message / select file in /load picker
↑ / ↓	Browse input history · navigate /load results
Tab	Autocomplete / command
Ctrl+T	Toggle reasoning display
Esc	Switch to navigation mode (or exit if chat is empty)
Ctrl+C	Exit chat
Ctrl+P / Ctrl+N · PgUp / PgDn · mouse wheel	Scroll chat

Mouse input is enabled by default. Set "enable_mouse": false in config.json to disable it.

Navigation mode (press Esc to enter):

Key	Action
i, a	Back to insert mode
j / k	Next / previous message
h / l	Jump to previous / next user message
gg, G	First / last message
Space	Toggle a mark on the current message
y	Yank current — or every marked — message to the clipboard
c	Clear all marks
/, ?, q	Slash command · help · exit

Slash commands

Command	Description
/load <query>	Live fzf-style file picker; pin a file as focused context
/select	Clear the currently focused file
/summarize	Summarize the focused file and save to its note
/sources	Documents cited in the last answer
/clear	Clear the conversation
/compact	Summarize older messages to free up context window
/export	Save conversation to markdown in notes_dir
/sessions	Session picker — load or manage past conversations
/new	Start a fresh session (current stays saved)
/skills	Manage custom prompt templates
/help	Show in-chat help and all keybindings

For deeper docs — tool-call internals, skill placeholders, session compaction, reasoning UI — see the Wiki or press /help in chat.

Browsing & search

Vim-style navigation everywhere. Cheat sheet:

Action	Key
Move / enter / up	j/k, l/h (or arrow keys)
Select	Space
To-read queue	t
Reading state	r
Edit metadata	ee
Search	/
AI chat	:gorae
Index library	:index
Help	:help

Search flags (after /):

• -t <title>, -a <author>, -y <year>, -c <keyword> (full-text), --tag <t1,t2>
• Examples: / -t transformer, / -a "Yoshua Bengio", / -c attention, / --tag llm,graph

Full-text index:

:index            index all documents under the watch root
:index here       only the current directory

Files whose size hasn't changed are skipped, so re-indexing is fast. The index uses SQLite's porter tokenizer, so "running" also matches "run".

Search results — every hit, not just one: a content search lists each matching document with its full hit count, and the detail pane shows a snippet for every occurrence (page-numbered for PDFs). Within the selected document you can walk through hits and open the file right where the match is:

Key	Action
j / k	Move between matching documents (result list)
n / N (or Tab / Shift+Tab)	Move the cursor between hits in the multi-hit box
Enter	Open the document at the selected hit's page
PgUp / PgDn	Page through the results list
Esc / q	Close results · / searches again

Opening at a specific page works with viewers that support it (zathura, sioyek, okular, evince); others open at the first page.

Tags: comma-separated in the metadata editor, hierarchical (ml/transformers matches the ml/ prefix). Browse all tags with :tags.

Bidirectional links: write [[filename]] in any Markdown file, run :index, and backlinks appear at the bottom of the info pane for every document that points to it.

Install

Option A — Pre-built binary (recommended)

Covered in Quickstart above.

Option B — Build from source

Requirements

• Go 1.21+
• Poppler CLI tools (pdftotext, pdfinfo, pdftocairo)
• Optional fallback preview: chafa for non-Kitty / non-iTerm2 terminals

# macOS
brew install golang poppler

# Debian / Ubuntu
sudo apt install golang-go poppler-utils

# Arch
sudo pacman -S go poppler

Build & install

git clone https://github.com/Han8931/gorae.git
cd gorae
./install.sh                                       # → ~/.local/bin/gorae (Linux) or /usr/local/bin/gorae (macOS)
GORAE_INSTALL_PATH=/usr/local/bin/gorae ./install.sh   # custom path

Linux + Kitty: with poppler-utils installed, Gorae uses native image-based PDF previews via pdftocairo. chafa is not required for the Kitty path.

Option C — Arch (AUR)

Two packages, pick whichever fits:

Package	What it does
gorae	builds from source via go (Arch-native)
gorae-bin	installs the pre-built x86_64 binary from the latest GitHub release

With an AUR helper (e.g. yay or paru):

yay -S gorae       # builds from source via go (Arch-native)
yay -S gorae-bin   # pre-built x86_64 binary from the latest GitHub release

Without an AUR helper — clone and build with makepkg, which installs the package through pacman:

git clone https://aur.archlinux.org/gorae.git      # or gorae-bin.git
cd gorae
makepkg -si                                         # -s pulls build deps, -i installs via pacman

To update later, git pull in the clone and re-run makepkg -si.

Both pull in poppler automatically and suggest chafa, zathura, and zathura-pdf-mupdf as optional dependencies.

Maintainer notes for keeping the PKGBUILDs in sync: see packaging/aur/README.md.

Recommended PDF viewer: Zathura

Any PDF viewer works, but Zathura with the MuPDF backend is a great fit: minimal, keyboard-driven, instant start, vi-style navigation.

sudo apt install zathura zathura-pdf-mupdf     # Debian / Ubuntu
sudo pacman -S zathura zathura-pdf-mupdf       # Arch

"pdf_viewer": "zathura"

Gorae auto-detects zathura on PATH, so the default works for most users.

Uninstall

rm <path-to-installed-binary>
rm -rf ~/.config/gorae        # config + theme
rm -rf ~/.local/share/gorae   # metadata, notes, db

Roadmap

See ROADMAP.md — what's shipped, what's in progress, and what's planned.

Contributing

PRs, bug reports, and feature ideas welcome. See CONTRIBUTING.md for dev setup, conventions, and the PR checklist.

License & credit

MIT. If you use Gorae in your project, documentation, or distribution, please credit Gorae by Han with a link to this repository.

The Gorae logo is inspired by the Bangudae Petroglyphs (반구대 암각화) in Ulsan, South Korea — one of the earliest known depictions of whales and whale hunting.

Acknowledgements

fineday38