Gorae

Browse, search, annotate, and discuss your document library without leaving the terminal.

What is Gorae?

Gorae is a small, keyboard-focused knowledge base for PDFs, EPUBs, and Markdown. It combines file browsing, metadata, notes, full-text search, and an optional AI assistant in one terminal interface.

Your documents stay as ordinary files. Metadata and the search index are stored locally, and AI is optional: use Ollama on your machine or configure an OpenAI-compatible provider.

Gorae may be a good fit if you prefer terminal tools, keep a folder-based paper library, or want fast search and notes without running a larger desktop app.

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
   mkdir -p ~/.local/bin
   chmod +x gorae && mv gorae ~/.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.

Highlights

Gorae is under active development. The interface and configuration may continue to evolve, but existing config files are migrated when new top-level settings are introduced.

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

Features:

• Library retrieval — relevant indexed passages are included with each question.
• Sessions — conversations are auto-saved; resume with /sessions, fork with /new.
• /load <query> — a live fuzzy picker focuses one or more papers 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.

"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
}

// 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":  "..."
}

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:

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:

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.

Themes and layout

Use :theme <name> to switch among bundled themes. After typing :theme , press Tab for the next theme, Shift+Tab for the previous theme, and Enter to apply the highlighted choice. :theme list shows every bundled theme, while :theme reload reloads a custom theme.toml.

Press ,n in normal mode to toggle the directory tree for the current session. Set its startup behavior in ~/.config/gorae/config.json (or the equivalent XDG_CONFIG_HOME path):

"show_tree": true

Install

Option A — Pre-built binary (recommended)

Covered in Quickstart above.

# macOS
brew install golang poppler

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

# Arch
sudo pacman -S go poppler

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

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

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

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

"pdf_viewer": "zathura"

Uninstall

rm <path-to-installed-binary>
rm -rf ~/.config/gorae        # permanently removes config + custom theme
rm -rf ~/.local/share/gorae   # permanently removes metadata, notes, and database

Roadmap

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

Documentation

• User guide — configuration, themes, keybindings, search, and AI
• Contributing — development setup and pull requests
• Roadmap — shipped and planned work

Contributing

PRs, bug reports, and feature ideas are welcome. See CONTRIBUTING.md for development setup and the pull-request checklist. If Gorae is useful to you, a star helps other terminal users find it.

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