lume-ai 0.1.1

  █   ▄  ▄  ▄▄▄▄▄   ▄▄
  █   █  █  █ █ █  █▄▄█
  █▄  ▀▄▄▀  █ █ █  ▀▄▄▄

Replies stream in as rendered Markdown — syntax-highlighted code, aligned tables, nested lists — under a calm animated status line. Conversations live on your own disk, in plain JSONL you can read, grep and delete. Five themes. One binary-free install.

Zero dependencies. Pure standard library: nothing to resolve, nothing to audit, nothing to break on upgrade day. Python 3.10 or newer.

  █   ▄  ▄  ▄▄▄▄▄   ▄▄
  █   █  █  █ █ █  █▄▄█
  █▄  ▀▄▄▀  █ █ █  ▀▄▄▄
  Opus 5

  /help for commands · Ctrl-C to stop a reply · Ctrl-D to leave
❯ explain a bloom filter in two sentences

lume
  A Bloom filter is a compact bit array plus k hash functions: to add an item you
  set the k bits it hashes to, and to test one you check those same bits.

  It answers "definitely not present" or "probably present" — false positives are
  possible, false negatives are not.

  ─ opus-5 · 1.4s · 412 in / 96 out · $0.004
❯

Install

pip install lume-ai          # provides the `lume` command

Or run it straight from a checkout — there is nothing to build:

git clone https://github.com/bobby-tablez/lume-ai && cd lume-ai
./lume-cli                   # or: python3 -m lume

Providers

lume speaks to three vendors through one interface. Set the key for whichever you want; anything you have a key for shows up in /models.

/models shows the live table with context windows and per‑million prices, and greys out any provider you have not set a key for.

export ANTHROPIC_API_KEY=...
lume                         # starts a session on the default model
lume --model sonnet          # or pick one

Switch mid-conversation with /model gpt-5.1, and pin the vendor when an alias is claimed by two of them: /model google:mini. Aliases resolve in provider order — Anthropic, then OpenAI, then Google. Any OpenAI-compatible endpoint — Groq, xAI, DeepSeek, Together, OpenRouter, Ollama, LM Studio — works by pointing OPENAI_BASE_URL at it.

Keys are read from the environment, used, and never written anywhere: not to the config file, not to a log, not into an error message, and never into a URL.

Use

lume                              # interactive
lume "explain this regex: ^\d{3}-\d{4}$"   # one-shot, then exit
git diff | lume "review this"     # stdin is folded into the message
lume --resume last                # pick up where you left off
lume --model haiku --no-thinking  # cheap and fast
lume --list                       # what have I got saved?

Commands

Session

Conversation

Model

Interface

Anything that is not a command is sent to the model. To send a line that really does start with a slash, double it: //not a command.

Typing

Configuration

~/.config/lume/config.json, written by /model, /theme and friends, or edited by hand. Every field also has an environment override:

Privacy

Conversations never leave your machine except as a request to the model provider you chose. Sessions are append-only JSONL under $LUME_HOME (or ~/.local/share/lume), directories 0700, files 0600. The prompt's history file is capped, 0600, and refuses to record any line that looks like a credential — paste a key at the prompt by accident and it is not written to disk.

Development

python3 -m unittest discover -s tests -v      # 1,400+ tests, no network, no fixtures

Every module is independently testable and each provider client takes an injected transport, so the suite never opens a socket and never needs an API key. SPEC.md is the interface contract the modules were built against.

Adding a provider is three things: a ModelSpec per model, a client exposing stream() and close() that yields lume.api.StreamEvent, and a line in lume/providers/__init__.py.

The name

lume — one syllable, rhymes with room. From lumen: light. It's what a terminal does when it's doing this well.

License

MIT © 2026 bobby-tablez