Your plants have a pulse. I

Hi, I'm Sprout. I watch a windowsill of plants and tell you, in plain words, how each one is doing — no guesswork: I read the soil myself and speak for the plant. (Watering? On my roadmap — and true to form, I won't claim it until it's calibrated.)

---

What Sprout is

Sprout is a small automatic plant-care system for a windowsill: capacitive soil-moisture probes on one or more ESP32-class boards — each reporting over Wi-Fi (untethered) or a USB-serial cable — with a Python logger and analytics behind them and a served dashboard out front. It watches the soil, classifies it into seven calibrated moisture bands, and (once calibration is in) will water before a plant is ever in trouble.

The minimum Sprout is deliberately small: a microcontroller and one soil sensor is already a complete Sprout (ADR-0028) — a pump, an OLED, and extra probes are optional enhancements, never an entry bar. And it's past the bench: since the wave-1 go-live (2026-07-04) the greenhouse runs live in soil — currently 11 plants, 8 of them with sensors, on 2 boards — reporting over Wi-Fi with each session saved to the catalog.

It's an open-source learning-and-portfolio build, made to be enjoyable to run and trustworthy to read — process and tooling sized to match, not over-engineered.

Sprout is developed with AI assistance — the maintainer works alongside AI coding tools — and AI-assisted contributions are as welcome as hand-written ones. Contribute however you work, with or without AI tools; the bar is the same either way: clear, tested, and kind.

Quick start

What you need first

A computer	macOS, Linux, or Windows 10/11. All three are supported and tested.
Git	git --version should print a number. If not: winget install Git.Git (Windows), xcode-select --install (macOS), sudo apt install git (Debian/Ubuntu).
A GitHub account	Only to contribute. Reading, cloning, and running Sprout need no account. To push, either add an SSH key or install the GitHub CLI and run gh auth login. Not a collaborator here? Fork the repo and branch from your fork — the normal open-source path.
Python	Nothing to install. uv fetches the exact locked interpreter for you.
A board + probe	Optional. Sprout runs, builds and tests without hardware; you need one only to read real soil.

Windows — where you clone matters. Windows' classic MAX_PATH is 260 characters and applies to the whole path, so we keep tracked paths under 200 and that leaves about 60 characters for your clone location. C:\dev\sprout is ideal; a deep …\OneDrive\Documents\GitHub\… can exhaust the budget and produce a checkout that fails — or silently lands incomplete — on a machine that has done nothing wrong. just doctor measures yours and tells you the headroom.

macOS / Linux

git clone https://github.com/OrangePeachPink/sprout
cd sprout
./scripts/bootstrap.sh      # installs uv + just if missing, syncs the env, wires the hooks
just start                  # run Sprout — opens the dashboard in your browser

Windows (PowerShell — works on the 5.1 that ships with Windows)

git clone https://github.com/OrangePeachPink/sprout
cd sprout
.\scripts\bootstrap.ps1
just start

That block is the whole path: bootstrap installs what's missing and then verifies it, printing the versions it just proved on your machine. It's safe to re-run — every step checks first and skips what's already there. Only git has to be there first (it's how you got here); your first PR walks that and the GitHub side.

Prefer to do it by hand, or curious what bootstrap does? The two tools are uv (env + runner) and just (the command menu):

uv sync                     # reproduce the exact, locked dev environment
uv run pre-commit install   # the conventions auto-apply on every commit

Or click Open in Codespaces for a ready-made env in the browser — the devcontainer installs both tools for you. Then just lists every command, and just check runs your local gate — lint, format, and the host test suites. Those two tools are genuinely all you need: just check never asks for a compiler. Only firmware work needs more, and it says so on its own path (just check-firmware).

Once the dashboard is up, click ▶ Start logging — that single action begins logging every connected sensor at once, whether it's plugged in over USB or reporting over Wi-Fi. On a brand-new install with no data yet, the empty-state hands you the same Start button, so day one is never a dead-end.

How it works

   probe          ESP32             classifier            Sprout
   ─────          ─────             ──────────            ──────
   capacitive  →  raw ADC count  →  seven moisture   →   a mood, a first-person line,
   soil read      (higher = drier)  bands (calibrated)   and — when ready — a pump

The chain is built on one rule: raw counts and the calibrated band are the reading. Any 0–100 figure is a clearly-labelled relative index between the wet/dry anchors — never presented as real volumetric water content. A plant's mood, its status color, and any watering all derive from the band, never from that index.

This is the beginning of the README. Read the rest at the original. Read the full README ↗