A program to distribute chores.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
.travis.yml travis: pedantic tests Sep 30, 2016
chorebot.cabal bump base upper bound Oct 11, 2016



Divvy up chores for housemates!

Chorebot is, at its core, a randomized algorithm that outputs a set of chore assignments which probably fulfill a set of requirements:

  1. Chore difficulty is evenly distributed
  2. Assignment of a particular chore is distributed evenly over time; for instance, a chore shouldn’t be assigned to the same person twice in a row
  3. Chores are assigned per a certain interval; for instance, once a week, once a month, etc.
  4. Permanent chores will always be assigned to a specific person.
  5. Chore vetoes prevent a chore from ever being assigned to a specific person.

What is this?

You are reading documentation for setting up and running the Chorebot program. You can find the source code on Github here:



You will need GHC (the Glorious Haskell Compiler) and a few Haskell packages to build and install Chorebot. The easiest way is to install Stack:

# to get the Chorebot code
git clone https://github.com/mjhoy/chorebot.git

# to install stack
curl -sSL https://get.haskellstack.org/ | sh

cd chorebot
stack setup # set up GHC
stack build # build dependencies and Chorebot

If everything builds, you can then execute Chorebot using Stack like so:

stack exec -- chorebot -h            # chorebote help
stack exec -- chorebot --list-chores # list chorebot chores
# and so on

WIP! Document how to:

  1. Set up all the data files (doers.txt, chores.txt and so on)
  2. Compile a static binary to send up to a shared host running Linux
  3. Define cron tasks for sending out weekly emails


Please see the CONTIBUTING.org file.

Defining chores

A list of chores is defined in chores.txt. A chore is defined in a special format, separated by a newline from other chores. The basic format is:

[Chore title]: [Interval] [Difficulty]

For instance,

Third floor bathroom: 1 Hard
Clean and scrub tub/shower/sink to remove grime, clean toilet bowl,
sweep and mop floors, clean countertop, clean mirror, change towels
and floor mats, replenish TP and soap as needed.

Water Plants: 1 Easy

Sweep/mop kitchen: 1 Medium
For the first week of the month, mop; otherwise sweep.

The description is optional.

The interval is the number of weeks until a chore is repeated. “1” means the chore is repeated every week, “2” every other week, and so on.

The difficulty is the word “Hard”, “Medium” or “Easy”. The exact calculation may be adjusted, but it should be something like: one hard chore is worth slightly less than two medium chores, and one medium chore is worth two easy chores.


Chorebot is free, open source software. It is licensed under GPL (GNU General Public License) v2. See the LICENSE file.