self-hosted  ·  open source

Errand.

An always-on personal agent you reach by text. It researches, runs commands, keeps files, remembers what matters, and stops to ask before anything it can't undo.

View the repo Run it in 3 lines

A conversation

telegram  ·  you & Errand
you › pull the 5 most cited papers on speculative decoding, one paragraph each, save it as a file errand › Done. Saved specdec.md to your workspace. Short version: the through-line is a small draft model proposing tokens a big model verifies in parallel... you › push those notes to my notes repo errand › I need approval to run: git push origin main. Reply /approve 9c1f04 or /deny 9c1f04. you › /approve 9c1f04 errand › Pushed. 1 file, commit a3f9c2.

What it has

Live web

Server-side web search and fetch. It reads the actual pages, not a stale memory.

A real shell

Commands run in a per-operator workspace directory. It does the work, then reports what happened.

Files

Read, write, list, delete inside the workspace. Long output lands in a file with a short summary in chat.

Memory

Durable facts about you in SQLite, recalled into every future conversation.

A browser

Optional Playwright session that keeps cookies and logins between runs.

Approval gates

Deletes, pushes, payments, sudo, curl-pipe-shell: paused until you reply /approve.

How it works

Telegram / REPL ─▶ handle_message ─▶ run_loop
                                       │  Claude Messages API
                                       │  (system + history + tools + thinking)
                                       ▼
                        stop_reason == "tool_use"?
                          ├─ web_search / web_fetch      (server-side)
                          ├─ run_shell / files / memory  (this process)
                          └─ irreversible? ─▶ create approval, tell you, stop
                                                   │
                                       /approve <id> ─▶ resume ─▶ run_loop

A small readable Python package: an agentic loop, a SQLite store, workspace-jailed tools, and two channels. No framework, no vendor lock-in beyond the model call.

Run it

git clone https://github.com/Shraman123/Errand && cd Errand
pip install -e .            # then put ANTHROPIC_API_KEY in .env

errand repl                 # talk to it in the terminal
errand run                  # or start the Telegram bot

Always-on: Docker image, systemd unit, and a Render blueprint are in the repo. errand run also serves /health so a platform keeps it awake.