Your machine, told what to do in plain words.

pico is a personal automation engine with 114 rules and zero dependencies. Every command resolves deterministically, every write is invertible, and the optional model can only propose a command — never run one. No account, no telemetry, no network at runtime.

licence: PolyForm Noncommercial 1.0.0 python 3.8+ tests: 491 passed dependencies: zero no network at runtime version 1.43.0
pico command console showing a resolved command, its source tier and its risk tier

The thesis

The rule engine is the spine.

Sixty-six patterns cover tasks, money, files, time, habits and text. They are regex, they are readable, and they produce the same output every time for the same input and state.

Unplugging the model removes convenience, not capability. Every command in the catalogue works with the translator deleted from disk.

The model is a translator, not an actor.

When enabled, a sentence goes out and a command string comes back. That string must match an existing rule, clear a metacharacter check, avoid the deny-list, and pass the same risk gate as typing. A hallucination cannot invent an action.

Every successful translation is stored as an alias, so the same phrasing never needs the model again. Usage decays toward zero on its own.

How a sentence becomes an action

01ruleExact pattern match. Deterministic, and the only tier that is.
02aliasA phrasing you taught once, stored locally, inspectable with aliases.
03typoOne-token repair at 0.80 similarity. tsks becomes tasks.
04fuzzyCatalogue match at 0.72, only for commands with no unfilled slots.
05teachThree candidates offered. Pick one and it is remembered permanently.

Nothing here guesses silently. dry <cmd> shows which tier resolved it and what it would touch; why shows what the last command actually did.

Risk tiers decide what needs a second look

TierApplies toBehaviour
safereads, arithmetic, listsruns immediately
writetidy, backup, fill, redactruns, records an inverse, reversible with undo
sendwa, mailrequires confirm; expires after 120 s
dangerunjob, habit del, safe deleterequires confirm and previews the affected set

A write-tier command proposed by the model is gated like a send. Typed by hand, it runs and stays undoable.

What it does with no network

Capture

Tasks, notes, shopping, events, a morning brief that totals the month so far.

Money

EMI, SIP, FD, simple interest, GST both ways, bill splits with the rounding stated, discounts, monthly caps.

Files

Sort a folder by type, zip a tree, find by name, fill a template, count and redact a text file.

Time

Clock, countdown, daily reminder, unit and temperature conversion, safe arithmetic.

Life

Habit streaks, a journal, contacts, WhatsApp and mail deep links that you still press send on.

Automation

Daily jobs, the ledger, universal undo, alias learning, slot dialogue, two-key approval, dry / why / log.

Command reference — 114 rules

Capture
tasks · add X · done N · undone N · del Ntask spine
recur daily X · due N DATE · overduerepeating and dated
remember k=v · recall k · forget knotes
buy X · shop · bought Nshopping
on MM-DD text · briefevents, daily brief
spend AMT CAT · expenses · budget CAT AMTmoney log and caps
Compute
emi P R N · sip A R Y · fd P R Y · si P R Yloan and investment
gst A R · split A N · disc A Rtax, bills, discounts
calc EXPR · convert V U to Uarithmetic, units
time · timer Nm MSG · remind HH:MM MSGclock and alarms
Files and text
tidy [PATH] · backup PATH · find NAMEorganise, archive, locate
templates · fill TPL k=vletter, invoice, email
safe delete PATH · quarantine · restore Nquarantine lifecycle
big files · old files Nd · dedupe files PATHdisk questions
count PATH · extract TYPE PATH · dedupe filessize, pull, find copies
sortlines PATH · dedupe PATH · redact PATHclean a text file
Life and meta
habit add X · did X · habits · habit del Xstreaks
journal [show N] · contact k=v · contactswrite and store
wa NAME MSG · mail NAME SUBJdeep links, you send
daily HH:MM CMD · jobs · unjob Nscheduled commands
dry CMD · why · log · undo N · aliasessafety and provenance
2key on/phone · approve CODE · timeline · replay TStwo-key, history, rebuild
when 22:30 then … · every 30m · file GLOB · not … by · clip matchestrigger DSL
unless away or weekend · watch FOLDER · away on · trigger logconditions, pauses, firings
chain NAME: a ; b · for each row in X.csvsequences and loops
card add Q|A · review · grade 5 · decide A|Bspaced repetition, a seeded pick
importcsv PATH TABLE · sql SELECT …CSV into sqlite, read-only out
csv filter/sort/pivot(:number) having order by · chart · net worthshell data verbs, payoff, position
doctor · fix · probe · probe writeself-check, repair, read probe, write probe

Measured, not claimed

PropertyMeasured
dependencies0 — Python standard library only
rules / catalogue / slots106 / 110 / 6
packs12
python source171,894 bytes across 29 files
console72,112 bytes, one HTML file
rule-path latency0.45 ms read and 1.7 ms write when empty; 1.45 / 9.5 ms at 5,000 tasks
engine heap0.1 MB
acceptance tests491 passing

Where the milliseconds go

A read command does a regex match and appends one ledger line. A write command also rewrites state.json and, every 25 changes, a snapshot — which is why the write path costs roughly six times the read path.

Both are inside the 5 ms rule-path budget. The size budgets are the project's own and CI fails the build when any part crosses: package 96 KB, packs 96 KB, console 96 KB — one ceiling for all three.

Install

From source, no pip

# any of: Linux, macOS, Windows, Termux
git clone https://github.com/drsamonline/pico
cd pico
sh install.sh          # or: powershell -f install.ps1

python3 ~/pico.py        # REPL
python3 ~/pico.py tasks  # one shot
python3 ~/pico.py --ui   # local console on 127.0.0.1:8765

Or run it in place

python3 pico.py --ui

# the console binds 127.0.0.1 and needs the
# token in ~/.pico/web.token. LAN mode is
# opt-in: --ui --lan, with a printed warning.

# phone: open the LAN address and use
# Add to Home Screen — it is one HTML file.

Windows, Linux and macOS one-file binaries are built by the release workflow on every tag. Android runs under Termux.

The console installs. It ships a manifest, icons and a service worker, so Add to Home Screen gives a standalone window that opens offline. The worker never caches /cmd or /api/state — the engine is always live. When a newer build is waiting, the console offers a Reload bar rather than swapping underneath you.

What it will not do

No abstractive summarising, translation or open-ended reasoning without the optional model. No two-way WhatsApp without Meta's Cloud API and a public webhook. Timers and jobs fire only while pico is running. Pure stdlib cannot do OCR, speech or QR rendering — those need an external tool.

Phrasing is literal plus learned aliases. It does not understand, and it will say so rather than pretend.

Data at rest is plain text. Notes, contacts and the journal are JSON in ~/.pico/. The ledger redacts the output of recall, journal, contacts and aliases, but the files themselves are not encrypted. Use full-disk encryption if that matters to you.

Support

Free, offline, accountless — and staying that way. Nothing is gated behind a donation: no accounts, no tracking, no network requests.

UPI (India)drsohilboi@ybl GitHub Sponsorsdrsamonline Ko-fiko-fi.com/matneo PayPalpaypal.me/drsohilmomin BooksAmazon author store More appsdrsamonline.github.io Emailsohilmomin2000@gmail.com

Licence

PolyForm Noncommercial 1.0.0. Use it, read it, change it, share it — for any noncommercial purpose. Commercial use needs a separate licence.

Built by Dr. Sohil Momin — homeopathic physician and builder of offline-first open-source software.

Read the full licence