How Lotus works

Install

Paste one line into Terminal:

Or with Homebrew:

Systems

Lotus runs on macOS (supported) and Linux (beta: tested in containers on Ubuntu 24.04, Debian 12, Fedora 42 and Arch). A native Windows version is in development and not available yet.

Linux

One line – no administrator rights, nothing outside your home folder:

The script checks the system, asks before it installs zsh (Lotus' engine) and shows the command first, downloads Lotus and fastfetch (checked against a pinned digest), and starts the setup. Lotus loads into zsh and bash; lotus setup adds its lines to the startup file of the shell you log in with (~/.zshrc or ~/.bashrc), or both. In bash the /commands need version 4.4; the live now-playing lines under the start screen are zsh only.

What the programs of your distribution provide is asked for only when a command needs it, with the exact command, for apt, dnf, pacman, zypper and apk: jq, ffmpeg, yt-dlp, imagemagick, playerctl, bubblewrap (the plugin sandbox), Chromium or Chrome (so that the AI can look at pages it builds). A plugin that needs a sandbox is refused, never run without one, where bubblewrap cannot start.

The AI program is one static file. A release carries it for Linux (x86_64 and arm64), Lotus checks its sha256 against the digest it ships with and deletes a file that does not match. With the Swift toolchain installed, Lotus builds it itself.

Windows

In development: a native PowerShell 7 module for Windows 11 and Windows Terminal, installed with winget or Scoop. It is not in a release yet, so there is nothing to install and no command here.

What works where

Yes = tested on that system · Partly = works, with the limit named · Soon = being built · No = not possible there.

First start

The first time Lotus runs, a short setup walks through five steps in the Matcha colors, with a small lotus that opens a little more with every step – esc goes back, nothing is saved before Finish, and everything can be changed later:

1. Welcome

   The interface language: English, Deutsch, Français or Español. The page switches to the language you point at.

2. You

   Your name, one of 13 themes (the lotus takes the colors of the theme you point at), and whether Lotus shows up in every new Terminal window.

3. Features

   Which parts of Lotus to turn on – app launcher, Homebrew, web search, weather, AI terminal, music, visualizer, video downloads, iOS tools, Minecraft, Remove BG.

4. Setup

   Only for what you turned on: your weather city, connecting Claude, the Remove BG model and output folder.

5. Review

   Everything at a glance, then Back or Finish. On Finish the lotus opens all the way and its pollen writes Hello and your name.

Run it again any time with lotus setup. Updating from Lotus 1.x or 2.x keeps your settings and skips the setup.

Using Lotus

Commands start with a slash and work in every Terminal window. The full list is on the commands page and in the terminal with /lotus cheatsheet.

Settings

Type /settings. Arrow keys to move, Enter or ←→ to change, v to preview the start screen, q to close.

Features

Lotus is made of features you can turn on or off – in the setup, in /settings → Features, or with lotus features. The list comes from data/features.tsv, the same file the website reads.

Configuration file

Everything is stored in ~/.config/lotus/settings.zsh – plain text, one setting per line. Your own logo is ~/.config/lotus/logo.txt. Temporary data (weather, now playing) lives in ~/.cache/lotus.

# lotus – settings (easier: lotus settings)
LOTUS_NAME='Alex'
LOTUS_THEME='matcha'
LOTUS_STARTUP='1'
LOTUS_WEATHER_LOCATION='Tokyo'
LOTUS_AI_PROVIDER='auto'
typeset -gA LOTUS_SHORTCUTS=('yt' 'url|https://youtube.com|on')

The AI terminal

Type /ai and the AI terminal opens: a chat you keep typing into – no /ai in front of every message. Ask questions, let it explain code, or let it work in the folder you started it in. lotus ai local puts a model on your Mac with Apple's MLX – no Ollama: it shows what fits your memory (Nucifera 20B – gpt-oss-20b tuned for Lotus, see nucifera-20b – Qwen3.6 27B, Qwen3-Coder 30B, Devstral Small 2, Qwen3 14B), downloads it once and loads it only while /ai runs. Like every model in /ai it can look at files, change them and run commands – as far as /permissions lets it.

Providers

/ai uses the first provider that works – or the one you pick with /model or in /settings. /ai status shows what is available.

In your browser

/ai server start opens Lotus AI in your browser – a chat page that Lotus serves itself on this Mac, at http://127.0.0.1:3000. It is the same AI as /ai, not a second one: the same providers, instructions, Lotus tools and permissions. Answers stream in as they are written.

It works in the folder where you started it, like /ai. /settings → AI → "Web chat: start with terminal" starts it with the first terminal window – off unless you turn it on. "Web chat: other devices" lets your phone or another Mac in your network open it with the link that contains your key; that connection is not encrypted, so only turn it on in networks you trust.

The AI terminal is a small Swift program that Lotus builds once on your Mac (about 15 seconds; needs the Command Line Tools: xcode-select --install). Keys come from the Keychain or $ANTHROPIC_API_KEY / $LOTUS_AI_KEY and are never written to a file. /ai command only suggests a command – it never runs it.

Remove BG

/bg remove photo.jpg removes the background and saves a transparent PNG. It runs on your Mac: no cloud, no upload, no account – after the one-time download it works offline. /bg remove without a path shows a drop zone: drag images from the Finder into it, or press ⏎ to take the image in the clipboard. /bg paste does that directly – a screenshot, “Copy Image” from a browser, or files copied in the Finder. A folder processes every image in it.

$ /bg remove ~/Pictures/portrait.jpg

    ◇ lotus / Background removed

    Input       ~/Pictures/portrait.jpg
    Output      ~/Pictures/Lotus/Background Removed/portrait_no_bg.png

    Model       BiRefNet
    Backend     MPS
    Resolution  1916 × 2608
    Time        2.16s

  ✓ Transparent PNG created

    o open   f show in Finder   r refine by hand   d discard   q done

Formats: PNG, JPG, WebP, HEIC, AVIF, TIFF, BMP, GIF. /bg models downloads, checks and removes models. BiRefNet (Peng Zheng et al.) and InSPyReNet (Taehun Kim et al.) are MIT licensed – see THIRD_PARTY.md.

Image converter

/img convert turns images and whole folders into another format – with macOS' own image engine, on your Mac. It reads what Preview reads: HEIC from the iPhone, PNG, JPEG, WebP, AVIF, GIF, TIFF, PSD, SVG, JPEG XL and RAW photos. Without a path it shows a drop zone: drag images or a folder into it, or press ⏎ for the image in the clipboard. Then pick the format, the quality and the size, and the lotus blooms while it works – with each image's size before and after underneath.

$ /img convert ~/Desktop/Holiday --to webp --max 1920

    ◇ lotus / Image converter

  ✓ 60 images in Holiday  (PNG 60 · 35.1 MB)

  ✓ 60 images → WebP   35.1 MB → 4.2 MB (-87 %)
    Saved in ~/Desktop/Holiday/WebP

Without questions: /img convert <image|folder>… --to <format> --quality <1–100> --max <pixels>. /img formats shows what your Mac reads and writes. The converter is a small Swift program Lotus builds once with the Command Line Tools; without them it uses macOS' sips.

Live Server and /html

Type /liveserver in a project folder – in VS Code's terminal too. It serves the folder on this Mac – and to your phone in the same Wi-Fi – opens index.html or, when there is none, a menu of all its pages, and reloads the browser whenever you save a file. Change only CSS, and only the styles swap – the page keeps its place.

  lotus / Live Server  ~/Code/my-site

    Address     http://127.0.0.1:5500  → a menu of 6 pages
    Wi-Fi       http://192.168.178.23:5500  for phones and computers in this Wi-Fi

  ✓ Live – the page reloads when you save. Ctrl-C stops it.

  14:02:11  ↻ css/style.css  styles only
  14:02:19  ↻ about.html

/html – your files as documents

/html turns your pages, style sheets and scripts as Word, PDF, Text, Markdown, OpenDocument or RTF. /html takes the page open in the browser, /html all puts every page, style sheet and script of the folder into a folder of their own – my-site/Word, my-site/PDF … As code, colored like in VS Code with the number of each line – or, for a page, what a visitor reads: headings, text, lists, tables, links and pictures.

    ◇ lotus / HTML converter

  ✓ All of my-site  7 pages · 2 style sheets · 1 script

  ✓ 10 files → Word  7 pages · 2 style sheets · 1 script · as code
    Saved in ~/Code/my-site/Word
    Left out: 4 images · 1 minified library (bootstrap.min.css)

Pets

Up to three little pixel pets live in your terminal. Type a pet's name and it answers – with Apple Intelligence on your Mac, in your language and with its own personality. /pets adopts, renames and feeds them; /help lets your pet find the right command, and in /ai it sits in the welcome box and its face is the spinner. Everything about them – and the prompt to make your own – is on the Pets page.

Adopted pets are in ~/.config/lotus/pets.tsv, your own kinds in ~/.config/lotus/pets/, hunger and what they remember in ~/.local/state/lotus/. A pet's name only calls it when no command, alias or function has that name.

Clock and keep awake

/clock opens a full-screen clock in the colors of your theme. Six designs: minimal, big digits, a retro seven-segment display with faintly lit unused segments, Matrix rain that forms the digits, a round analog face drawn with braille dots, and a world clock with a day-and-night bar for every city. It uses your Mac's own clock and starts no background process.

The design, seconds and the cities of the world clock are in /settings → Clock (time zones like Europe/Zurich). Keep awake uses macOS' own caffeinate: it keeps running when you close the terminal, ends by itself when the time is up, and the start screen shows it while it is on. Lotus only ever stops the caffeinate it started itself.

Log

/lotus log shows what Lotus did – commands, settings changes, downloads, installs, the AI's tool use, Remove BG stages and every error – with the time and the part of Lotus it came from.

The file is ~/.local/state/lotus/lotus.log, rotated at 1 MB and trimmed after the retention time (7 days by default). Keys, tokens and passwords are masked, your home folder is written as ~, and nothing leaves your Mac.

Update and uninstall

Privacy and security

Troubleshooting

Changelog