| README.md | ||
Waxwing
Local-first gardening assistant. Grow schedules, plant tracking, fertilization and soil management, camera health assessment, repotting guidance, and smart irrigation control — no cloud required.
Part of the Circuit Forge LLC menagerie — AI for the tasks the system made hard on purpose.
Status: Backlog — not yet started. See the roadmap for priority order.
What it does
Waxwing tracks your plants, trees, and grafts from planting to harvest: timed care reminders, multi-year growth logs, variety registries, and LLM-assisted diagnosis when something looks wrong.
The Bohemian waxwing (Bombycilla garrulus) roams in tight flocks that arrive at a berry source at exactly the moment of peak ripeness — not a day early, not a day late. That precision timing is the entire point of the product. Your tomatoes don't care that you forgot to check them.
Why it is hard
Home gardening fails quietly:
- Planting windows are narrow and easy to miss without a record of last year's dates
- Graft take and tree health degrade slowly, so problems are invisible until they are not
- Variety tracking across multiple beds and seasons requires memory most people do not have
- Commercial apps are either too simple (reminders only) or too complex (farm management software designed for acres)
Core pipeline
Add plants and trees to your registry (species, variety, planting date, location)
→ Generate care schedule (watering, feeding, pruning, spraying)
→ Timed reminders → Human confirms action
→ Log observation (photo, note, measurement)
→ LLM-assisted diagnosis from photo or symptom description
→ Build multi-year growth and harvest history
Feature areas
- Plant registry: common name, Latin binomial, variety, rootstock, grafting date and scion source
- Grow calendar: planting windows, last frost integration, days-to-maturity countdowns
- Companion planting: bed-level compatibility matrix showing beneficial pairings, pest deterrence guilds (Three Sisters and others), and plants to keep separated; LLM explains the reasoning behind each pairing
- Light mapping: track sun exposure per bed across seasons; input sunrise/sunset angles for your coordinates or log direct observations; Waxwing recommends plant placements based on actual light hours rather than generic "full sun / part shade" labels
- Graft tracker: union success rate, scion-rootstock compatibility notes, photo log
- Diagnosis: photo upload or symptom description; visual model suggests deficiencies, pests, or disease
- Fertilization scheduler: per-plant feeding schedule based on species, growth stage, and season; tracks NPK (nitrogen, phosphorus, potassium) applications with dosage and product used; adjusts schedule when the plant is in a heavy-feeding window (flowering, fruiting, rapid vegetative growth) vs. a rest period
- Soil composition and amendment suggestions: enter lab soil test results or photograph a test strip and Waxwing interprets pH, NPK levels, and micronutrient readings against the target range for your specific plants; suggests organic amendments (compost, worm castings, bone meal, kelp) or specific fertilizers to close the gap; tracks compost pile readiness using temperature and moisture curves if you log those separately
- Repotting assessment: for container plants, Waxwing tracks pot size, planting date, growth rate, and soil dry-out speed; visual model flags root-bound indicators from photos (visible root escape at drainage holes, surface root crowding, plant-to-pot ratio); recommends pot size step-up and optimal timing by species
- Water needs assessment: point your camera at a plant and the visual model evaluates water stress indicators (leaf curl, turgor, color shift, soil surface); output is a recommendation, not a command
- Smart irrigation control: integrates with Home Assistant and Orbit B-hyve (IoT irrigation controllers) to trigger watering runs; each plant or zone runs in one of two modes:
- Suggest mode (default): Waxwing sends a notification with the assessment and recommended run time; you approve before anything opens
- Automate mode (opt-in per plant): watering triggers automatically within parameters you set (maximum daily volume, soil moisture floor, blackout windows); alerts you when readings fall outside your configured bounds
- Harvest log: yield by variety and season; searchable history
- Offline-first: all data stays local; no account required for core features
Privacy · Safety · Accessibility
Privacy: Your grow data stays on your device. No account required for core use. Cloud sync (Paid tier) is opt-in and encrypted in transit.
Safety: Diagnosis and water stress assessments are starting points, not instructions. Automated watering (automate mode) requires per-plant opt-in and explicit parameter bounds; no valve opens without either user approval or your pre-configured limits being met. Pesticide and treatment recommendations always link to label instructions and require user confirmation before logging.
Accessibility: Plant names displayed in both common and Latin. Care reminders support multiple notification modes. High-contrast and large-text modes follow system preferences.
Tiers
| Tier | What you get |
|---|---|
| Free | Full plant registry, grow calendar, harvest log, local LLM diagnosis, water stress assessment, sensor integration (local network) |
| Paid | Cloud sync across devices, photo backup, community variety library, irrigation controller integration (Home Assistant, Orbit B-hyve) |
| Premium | Fine-tuned visual model for your specific varieties and conditions, multi-site support, sensor fleet management |
Product code
License key format: CFG-WXWG-XXXX-XXXX-XXXX
Get involved
Waxwing is pre-development. The best thing you can do right now is open an issue with:
- A specific pain point you hit with existing garden tracking apps
- A plant type or growing style (tropical houseplants, fruit trees, food forest, etc.) you want supported
- Features you have tried in other tools and found lacking
Early issues shape what gets built first. Star the repo to follow progress.
Tech notes
- Built on the shared circuitforge-core scaffold
- Visual model: local vision LLM for leaf/fruit diagnosis, water stress assessment, nutrient deficiency identification, and repotting indicators (root escape, surface crowding, plant-to-pot ratio)
- Soil test interpretation: pH, NPK, and micronutrient result parsing from lab report text or test strip photo; amendment recommendation engine keyed to plant species target ranges
- Calendar integration: iCal export for reminders
- Data format: SQLite local store, JSON export for portability
- Graft registry: tracks rootstock, scion, union date, take confirmation, and annual vigor notes
Sensor integration layer:
Waxwing ingests readings from a wide range of garden sensor hardware. Any sensor that can publish data over the local network is a candidate:
| Transport | Example hardware | What it provides |
|---|---|---|
| Home Assistant entity | HA soil moisture, temperature, humidity sensors | Direct pull via HA REST or WebSocket API |
| MQTT broker | DIY Arduino/ESP32 builds, Zigbee soil sensors | Subscribe to topic per bed or per plant |
| LoRa / LoRaWAN | Custom field sensors, The Things Network nodes | Long-range soil and microclimate readings from far corners of a property |
| RF (433 MHz / 915 MHz) | Budget wireless soil probes, weather stations | Received via RTL-SDR or dedicated gateway |
| Orbit B-hyve API | Smart irrigation controllers | Trigger watering runs; read zone history |
| HTTP polling | Any sensor with a local REST endpoint | Generic fallback for anything with a web interface |
Sensor readings fuse with visual model output and grow calendar data to produce the water needs assessment. Camera vision and sensors are complementary: sensors give ground-truth soil state, camera gives above-ground plant response.
License
Business Source License 1.1 — free for personal non-commercial self-hosting. Converts to MIT after four years. Commercial use requires a paid license.