botany: a terminal plant that dies if you forget it for five days

The mechanic is a watering deadline, and the deadline is the point

botany is described as a command line, realtime, community plant buddy. You have been given a seed that will grow into a beautiful plant, and you check in and water your plant every 24 hours to keep it growing. Five days without water equals death, and the plant depends on you and your friends to live. That is the whole design, and it is a good one, because a virtual pet without a cost is a screensaver. The cost here is one command a day, and the social layer is the pressure that makes it stick. The README quotes Alan Watts on coming out of the world as leaves from a tree, and credits tilde.town for the inspiration, which is the community this comes from. The audience is someone who wants a small, text-first, slightly demanding companion rather than a productivity tool.

Getting started is a clone and one Python command

botany is designed for unix-based systems, and the getting started section is two steps, quoted here as the README writes them:

botany is designed for unix-based systems. Clone into a local directory using `$ git clone https://github.com/jifunks/botany.git`.
Run with `$ python3 botany.py`.

There is one detail in the README that is easy to skim past and important to get right. botany.py must initially be run by the user who cloned or unzipped botany.py, because this initializes the shared data file permissions. The reasoning becomes clear once you look at the multiplayer feature: the plant data lives in the user's home directory, and a shared server needs several people to be able to read and write it. The project is by Jake Funke, with the screencap and the community presence on tilde.town, and the requirements list a unix-based OS such as Mac or Linux, Python 3.x, and a recommended 80x24 minimum terminal with a fixed-width font.

The data file is a plain JSON document you could read yourself

The plant state is not hidden in a database format you cannot inspect. Data files are created in the user's home directory along with a JSON file that can be used in other apps, and the README shows the shape of one record:

{
  "description":"common screaming mature jade plant",
  "generation":1,
  "file_name":"/home/curiouser/.botany/curiouser_plant.dat",
  "owner":"curiouser",
  "species":"jade plant",
  "stage":"mature",
  "age":"24d:2h:16m:19s",
  "rarity":"common",
  "score":955337.0,
  "mutation":"screaming",
  "last_watered":1529007007,
  "is_dead":false
}

That is a useful design decision for a project that invites other programs to read its data. The age is a duration string, the last watering is a Unix timestamp, and the file path points into a hidden directory under the home directory. The `is_dead` flag and the `mutation` and `rarity` fields are what make a plant more than a counter.

Growth continues when the app is closed, which is the trick

The features list mentions a persistent aging system that allows your plant to grow even when the app is closed. That single line changes what the program is. Without it, checking in would be a transaction and the plant would only advance when you looked. With it, the plant's age is derived from the elapsed time, so the cost of not visiting is the plant continuing to grow toward its limit and, past the five day window, dying. It also means the watering deadline is measured against wall clock time rather than against your sessions, which is what makes the deadline real. The generations mechanic builds on the same clock. Each plant you bring to its full growth potential rewards you with 20% growth speed for the next plant, so progress compounds across the plants you grow, and random and rare mutations can occur at any point in a plant's life.

The community garden is a SQLite file shared by whoever logs in

The multiplayer feature works through a SQLite Community Garden of other users' plants, for shared unix servers. The README describes it as watering your friends' plants and seeing who has visited your garden. That is a specific deployment model, a shared host where several people run the same program against the same database, and it is why the initial run has to be done by the account that cloned the code. There is a maintenance job attached to it too. A once-weekly cron on `clear_weekly_users.py` should be set up to keep weekly visitors tidy, which tells you the shared database accumulates records that need pruning on a schedule. The repository listing backs the structure up, with `botany.py` as the entry point, `plant.py` for the plant logic, `menu_screen.py` for the interface, `completer.py` for input completion, `botany-view.py` as a separate viewer, `testsql.py` for the database layer, and an `art/` directory holding the ASCII artwork.

The interface is curses, and the art is twenty species of ASCII plant

The interface is a curses-based menu system optimized for an 80x24 terminal, and there are 20 or more species of plants with ASCII art for each. There is also colored plant art, and the color can be turned off by setting the environment variable `NO_COLOR` or by setting `PYTHON_COLORS=0`. The choice of curses is the one that makes the whole thing work on a unix box over SSH, which is the intended setting, and the ASCII art per species is what gives each plant an identity rather than a number. The 80x24 optimisation is also a real constraint on the art, and the requirement for a fixed-width font is a consequence of it. The `NO_COLOR` support matters more than it looks, because the convention of honouring it is what lets the program behave in a piped or logged context.

Where botany is the wrong tool

Two limits are obvious once you understand what the program is for. The first is that it is a foreground interactive program, and everything about it assumes a person at a terminal. There is no daemon mode, no API for a bot to poll, and no non-interactive mode documented in the README, so you cannot deploy it as a service or wire it into a monitoring stack. The second is the requirement of a real unix machine with a home directory and shared file permissions, which rules out Windows and makes it awkward in a container where the home directory is ephemeral. The to-do list also shows the project is still growing, with plant pollination and cross-breeding to open up second-generation plants, sharing seeds with other users, global events such as rain storms and heat waves, and hybridization with lineage tracking all still open. If you were looking for something to build on rather than to play with, those items are the honest description of the current state.

Editorial conclusion

botany fits someone who wants a small, text-based thing with a bit of social pressure attached to it, running on a unix box they already log into, and who is willing to check in once a day. It is the wrong tool for a background service, a monitoring tool, or anything with a service level, because the entire premise is that a human attends to it. It is also the wrong tool on Windows, since the requirements name a unix-based OS and the shared data file permissions assume a multi user machine. Before you install it, read the note about the first run, because botany.py has to be run initially by the user who cloned it so that the shared data file permissions are set up correctly, and that step is what makes the community garden work.

Frequently asked questions

Official sources

1. Issues
2. jifunks/botany on GitHub
3. License: ISC
4. README