Zetsu

What it is

ZETSU turns your accumulated knowledge into a queryable assistant. It ingests your writeups, lab solutions, bug bounty reports, and security blogs, then allows you to query them in natural language during engagements. No cloud, no SaaS, your knowledge stays yours.

How it works

• Ingestion pipeline reads your sources and performs FARR extraction to produce structured units (Finding, Action, Reasoning, Result).
• Hybrid retrieval combines BM25 exact token matching with vector search for semantic similarity; results are fused via Rating-Refined Fusion (RRF).
• Cross-encoder reranker reorders retrieved chunks by relevance before passing to the LLM.
• Two response styles: Operator mode (commands first) and Concept mode (reasoning first).
• Multiple LLM backends supported: Anthropic, OpenAI-compatible backends, or local Ollama. Separate backends for ingest and query.
• Source types include local markdown files, single URLs, GitHub wikis, Atom/RSS feeds.
• Persistent chat history stored at ~/.zetsu/history/YYYY-MM-DD.json, browsable with /history.
• Interfaces: TUI, Web UI, and CLI.

Getting started

Installation:

git clone https://github.com/chaelsoo/zetsu
cd zetsu
pip install -r requirements.txt

Set up your API key:

cp .env.example .env
# edit .env and add your key

Quick start:

1. Add your writeups by dropping .md files into docs/.
2. Configure sources in config.toml with an example provided in the README.
3. Ingest:

python zetsu.py ingest

4. Use it:

python zetsu.py tui       # terminal UI
python zetsu.py web       # browser at localhost:8000
python zetsu.py ask "how do i abuse SeImpersonatePrivilege"

CLI reference includes ingest options, UI commands, and stats:

python zetsu.py ingest                 # ingest enabled sources
python zetsu.py ingest --force         # wipe and rebuild everything
python zetsu.py ingest --dry-run       # estimate without making LLM calls
python zetsu.py ingest --all-sources   # enable all sources regardless of enabled flag
python zetsu.py tui                    # terminal UI
python zetsu.py web                    # web UI
python zetsu.py ask "query"            # one-shot CLI
python zetsu.py ask "query" --style concept
python zetsu.py stats                  # vector store stats

Source types and extract modes are described, including markdown_dir with farr extraction, headers, and markdown_file with farr+narrative options.

Recent releases

• None

Traction

• Stars: 148 (no recent daily/weekly breakdown provided in README)

License

• License: none listed