tref – Terminal Reference Manager

Your Offline, Semantic Cheat-Sheet Layer in the Terminal

tref is a lightweight Python CLI (and library) that turns your personal notes, command snippets, and tool documentation into a fast, meaning-aware reference system — right inside your shell.

No browser tabs. No Google. No sending your queries to the cloud.
Just type what you want to know → get relevant, version-specific snippets → keep coding.

The updated version (v0.3+) focuses on reliability, privacy, and real daily workflows instead of flashy demos.

---

Why I Built (and Rewrote) It

I was tired of:

• git rebase --help being too verbose
• Forgetting pandas.groupby exact syntax mid-debug
• Opening 8 tabs for the same kubectl patterns
• Searching Stack Overflow / cheat.sh and getting outdated or noisy results
• Worrying about privacy when using online AI tools for quick lookups

I wanted something that:

• Lives entirely locally (~/.tref)
• Understands intent (“how to safely rebase without losing work”) not just keywords
• Handles version differences (pandas@2.2 vs pandas@2.0)
• Lets me curate my own KB in plain markdown
• Works offline 99% of the time
• Feels fast enough to use 20–30 times a day

That became tref.

---

Core Idea: Semantic + Local + Versioned

tref indexes markdown files (your cheat sheets) using FAISS vector search + embeddings.
You query in natural language → it returns the most semantically similar chunks → optionally asks a local LLM (Ollama) to turn raw snippets into clean explanations.

Everything stays on your machine unless you explicitly pull pre-built indexes from a trusted source (with checksums + optional cosign verification).

---

Key Features

• Semantic search — Ask “how to merge branches without fast-forward” → gets relevant git snippets even if words don’t match exactly
• Version awareness — tref "pandas@2.2 groupby multiple columns agg mean" vs older versions
• Interactive live mode — tref live → persistent REPL for back-and-forth querying
• Curated markdown KB — Strict schema (frontmatter + required sections: Signature, Examples, Gotchas, etc.)
• Offline-first — Build/use local indexes; optional secure remote updates
• Trust model — Freshness policies (strict|warn|offline-only), checksums, signatures
• LLM augmentation — --llm → Ollama generates natural-language answers from retrieved chunks
• Python API — from tref import ask for scripting/integration
• Maintenance tools — tref doctor, tref eval, tref bench, tref status

---

Core Commands (Daily Workflow)

# Quick lookup
tref "how to safely rebase current branch"
tref "pandas@2.2 groupby agg mean multiple columns"

# Interactive session
tref live

# Add/edit your own KB
tref --add git          # opens editor for new git.md
tref --edit pandas@2.2  # edit existing

# List / manage
tref --list
tref --delete kubectl

# Rebuild index after edits
tref --update-embeddings

# Pull trusted remote indexes (with verification)
tref update --strict-verify

# Config tweaks
tref config set --freshness-policy offline-only --top-k 6
tref config show

---

Technical Direction

• Language & Packaging: Python (modern pyproject.toml)
• Vector Store: FAISS for ANN retrieval
• Embeddings: Local model (likely sentence-transformers style)
• LLM (optional): Ollama integration (--llm --model llama3.1:8b-instruct)
• Storage: ~/.tref/indexes/ — per-library/version dirs with index.faiss, chunks.jsonl, meta.json
• KB Format: Markdown with YAML frontmatter + strict headings (Signature, What It Does, Examples, Alternatives, Gotchas, References)
• Update Safety: Atomic swaps, checksum verification, optional cosign signatures
• Extensibility: Custom remote endpoints, configurable freshness policy

Kept deliberately lightweight — runs fine on a normal laptop, no Docker or heavy deps required.

---

Why It Matters (to Me)

tref isn’t trying to replace Google, ChatGPT, or man pages.
It’s my personal terminal memory — tuned to how I think and work.

• Reduces context-switching friction
• Remembers the exact flags I always forget
• Learns my preferred patterns over time (as I curate better KB)
• Stays private — no telemetry, no prompts leaving my machine
• Works offline on flights or spotty Wi-Fi

In a world full of cloud AI assistants, tref is the quiet, reliable local alternative for when you just need the right command now, without leaving vim/tmux/zsh.

---

Links & Next Steps

• Live Docs / Landing: t-ref.pages.dev
• Source Code: github.com/pavandhadge/tref
• Install: pip install git+https://github.com/pavandhadge/tref.git (or clone + pip install .)

Try it if you:

• Live in the terminal
• Hate tab-switching for syntax
• Want semantic search without phoning home
• Like curating your own knowledge base

Feedback, new KB ideas, or bug reports → open an issue or ping me on X @pavan_dhadge.

Happy (faster) hacking.