          ,
       .-/ \-.
   .-.( (   ) ).-.
  (   \ \   / /   )
   '-._\_\_/_/_.-'
~~~~~~~~~~~~~~~~~~~~~~

lotus · a local agent for Ollama that fits small models

Files, shell, web and a real browser, driven by a 4–8B model on your own machine. Pure Python standard library, nothing to configure.

Install

curl -fsSL https://raw.githubusercontent.com/Het-Joshi/lotus/main/install.sh | sh

Install with browser control (adds Playwright and Chromium, about 150 MB)

curl -fsSL https://raw.githubusercontent.com/Het-Joshi/lotus/main/install.sh | sh -s -- --browser

Linux and macOS. Uses uv or pipx if you have them, otherwise a private virtualenv; never needs root. Elsewhere: pip install "lotus-agent @ https://github.com/Het-Joshi/lotus/archive/main.tar.gz". You'll need Ollama and a model, e.g. ollama pull qwen3:4b.

Ask it anything

A few things to try. It asks before anything that pays, sends or deletes.clicktap for another

What it looks like

An example session in a dark terminal.

❀ what's using port 8080, and is it safe to stop?

  ⚙ shell ss -ltnp 'sport = :8080' ✓ 0.1s
  ⚙ shell ps -o pid,etime,cmd -p 41873 ✓ 0.0s

Port 8080 is held by uvicorn app.main:app --reload (pid 41873),
started 3 hours ago from ~/work/api. It's your dev server, so
stopping it only affects local testing.

❀ stop it

  ╭─ approve shell
  │ kill 41873
  ╰─ ✓ allowed
  ✿ vichāra · reflecting · 2s · esc to stop
  ╰ qwen3:4b   2.1k in · 46 out   38 tok/s   4.2s   ❀❀······ 18% of 16k

Things your agent probably can't do

Browse onions: /tor on sends the browser, search and page reading through Tor, and any .onion address switches over by itself. DNS stays inside Tor, WebRTC can't leak your IP, QUIC is off. Tested against check.torproject.org and a real WebRTC probe.
Dodge phishing: Pages are checked against live malware and phishing lists before they load. Hidden "ignore your instructions" text is flagged. Passwords and card numbers need your yes even in auto mode, and .exe downloads are refused.
Drive a browser like you: Private windows on demand, incognito by default or a profile that remembers logins, Chromium or Firefox. Batches clicks and typing into one step. Hit a captcha? It hands you the window and carries on.
Stop looping: Small reasoning models think in circles. lotus notices, cuts it off, and gets the answer anyway.
Work while you sleep: lotus watch onion-watch --every 30m --notify checks your hidden services and pings your desktop.
See and draw: Attach a screenshot and a text-only model hands it to a vision model. Charts, trees and tables render in the terminal.
No strings: No API keys, no telemetry, no dependencies, no cloud. Works in a pipe and over SSH.

Why it exists

Most agent harnesses are built for frontier models and then pointed at Ollama. On a small local model they break quietly:

Silent truncation. Ollama drops whatever doesn't fit its default context, without an error. lotus reads each model's real limit, sizes num_ctx for every prompt, and warns before anything is cut.
Broken tool calls. Small models often write tool calls as text, or with the wrong argument names. lotus uses native calls when it can and rescues and repairs the rest.
Context rot. One log file fills the window and the model forgets the task. lotus pages long output, retires stale reads, keeps the plan at the end of the window, and compacts history into a structured summary.

The system prompt is about 250 tokens. Tools come in packs that load only when needed.

What's in it

Tools: Files, shell, grep, web search and fetch (optionally over Tor), clipboard, apps, notifications, charts and tables in the terminal, sub-agents with a fresh context.
Browser: Pages become text plus numbered elements, so a small model can say browser_click("3"). Asks before buy, send or delete buttons. Known malware and phishing pages are blocked, pages that try to give it orders are flagged, passwords and card numbers always need your yes. Goes through Tor with /tor on, .onion included.
Control: Esc stops a turn anywhere: the reply, a running command, the browser, sub-agents. Type while it works and your message is queued. Commands, writes and form input ask first.
Memory: LOTUS.md keeps instructions and facts for each project. .LOTUS_REM.txt notes where the last session left off, so the next one picks up there.
Extending: MCP servers, Python plugins (a function and a docstring is a tool), and recipes: saved prompts you can run on a schedule.
Requirements: Python 3.9+ and Ollama. No other dependencies; Playwright only for the browser.

Use

`lotus`	interactive session
`lotus "what's using port 8080?"`	one question, then exit
`git diff \| lotus "commit message"`	pipe anything in; output is clean markdown
`lotus -r`	resume the last session
`lotus run standup`	run a saved recipe
`lotus doctor`	check Ollama, models, browser, Tor

Inside a session, type / for every command, @path to attach a file, !cmd to run a shell command yourself. The docs cover the rest.