esbi-cli

Save PDFs and links. Get a wiki of notes you can read instead of the originals.

esbi-cli is a command-line worker (sb) that reads what you save (PDFs, web pages, email, clips) and writes a Markdown wiki: an executive summary, the key ideas, a glossary, verbatim quotes, a concept diagram, the figures, and links to the notes you already have. Every morning it builds an index note to start from. It works with local models (Ollama, LM Studio), with your Claude subscription, or with an API key. It follows Karpathy's LLM Wiki pattern, and the model never touches your files: it only returns JSON that the program validates and then writes.

What a note looks like

You save a link or a paper. A few minutes later there is a note like this (abridged, from a Wikipedia article, written by llama3.2 on a laptop; the notes are in English unless you set [notes].language = "es"):

## Executive summary
The Zettelkasten is a method of note-taking and knowledge management developed by Niklas Luhmann,
which involves creating a network of interconnected notes and ideas. It emphasizes the importance of
linking and connecting ideas, rather than simply collecting or storing them.

## Key ideas
- **The Zettelkasten system emphasizes the use of index cards to organize and connect ideas.** This
  approach allows users to create a network of interconnected notes, rather than a linear sequence of thoughts.

## Key terms
- **Zettelkasten**: A system of note-taking and personal knowledge management that consists of small
  items of information stored on paper slips or cards.

## Key quotes
> "Every one admits nowadays that it is advisable to collect materials on separate cards or slips of paper."

## Concepts
- [[Index card file]]

## Entities
- [[Niklas Luhmann]]
- [[Roland Barthes]]

Quotes are checked against the source word for word, glossary terms must appear in it, diagrams are drawn by code, and PDF figures are copied next to the note. Details: How a note is made.

Who it is for

People who save more than they read: papers, articles, newsletters, YouTube talks. You decide what to read from a good summary, and you can ask your own wiki questions (sb ask) and get answers that cite your notes. It runs on your machine, on macOS (the only supported system for now).

Install

brew install rubenamaury/esbi-cli/esbi-cli          # macOS (Homebrew)
# or, from PyPI with uv:
uv tool install esbi-cli

Then set it up. sb init is an installer: it asks what you use and every question is optional.

sb init        # vault folder, Obsidian or not, local model / Claude subscription / API, nightly job, backup
sb doctor      # checks the whole setup and says what to fix

A walk-through from install to a first note is in Getting started; other ways to install (unreleased code from git, a wheel, a source checkout) are in Install.

First five minutes

sb add https://example.com/a-good-article     # a link
cp ~/Downloads/paper.pdf ~/Documents/Obsidian/esbi/inbox/    # or drop a PDF in inbox/
sb run                                        # reads, writes the notes (a few minutes per source)
sb today                                      # opens today's index note

In the index note, tick - [x] next to what you have read and run sb index. Ask a question with sb ask "what is an agent harness?". Getting started shows every step with its output, and A first week teaches the habit.

What is optional

The basics are PDFs and links. Everything else you can skip, or add later:

Privacy: what leaves your machine

With either cloud choice, email is never sent: it is read only by a local model ([llm.private]), and the cloud model is never shown email pages. The mail password is stored in the macOS Keychain, never in a file; the app only reads mail, it never deletes it; URLs are fetched only on public addresses. Details: Safety and privacy.

How it works

 you save                         the worker (sb run)                          you read
 ────────                         ───────────────────                          ────────
 sb add / inbox/ PDFs   ┐
 Web Clipper clips      ├─► queue ─► extract ─► read in chunks ─► model writes a   ─► wiki/ notes, index.md,
 forwarded email        ┘   (SQLite)  (web, PDF)  (notes per chunk)   JSON edit plan       log.md, wiki/daily/  ◄── start here

raw/ keeps the originals and is never edited; wiki/ holds the notes the worker writes and you edit freely; SCHEMA.md holds the conventions the model is given. The vault is its own git repository: every ingested source is a commit, so any change can be reviewed or reverted. More: How it works, Internals.

Documentation

The same pages are published as a website: https://rubenamaury.github.io/esbi-cli/ (documentation under /docs/).

Requirements

Python 3.12 or later (installed for you by brew or uv), macOS 13 or later (the PDF reader ships no build for older ones; macOS is the only supported platform for now, Linux and Windows are not supported: it was tried on Ubuntu in containers and the problems found there were fixed, but nothing is promised), git (optional: version history and backup), and one way to run a model: Ollama or LM Studio locally, the Claude Code claude tool signed in to a subscription, or an API key. sb doctor checks all of it.

Status

Version 0.x: it works and is used daily, but commands and the config format can still change between minor versions; see the changelog. Quality depends on the model: a small local model writes useful but unpolished notes; a stronger model writes noticeably better ones. Known limits are in Known limits; open work is in the issue tracker.

Contributing and security

Bug reports and ideas are welcome: CONTRIBUTING.md. Please report vulnerabilities privately: SECURITY.md.

License

MIT. PDFs are read with PDFium through pypdfium2 (BSD-3-Clause or Apache-2.0); no dependency of esbi-cli is under the AGPL, and a test keeps it that way.