Tasks

Creating Tasks

Tasks are the core of HelmKeep. Members with the tasks.create permission can create tasks from the Tasks page. When creating a task, you can set:

Title and description: What needs to be done
Category: Group tasks by type (e.g., Kitchen, Bathroom, Yard)
Due date: When the task should be completed
Reward amount: Optional monetary reward for completion (when financial tracking is enabled)
Assignee: Optionally assign the task to a specific member
Tags: Apply custom tags for organization and filtering
Perks: Attach non-monetary rewards
Recurrence: Set up auto-generation on a schedule
Bidding: Enable bidding to let members compete for the task

Task Status Workflow

Every task follows a defined lifecycle:

OPEN→IN_PROGRESS→PENDING_APPROVAL→COMPLETED

OPEN: The task is available and waiting to be picked up or assigned
IN_PROGRESS: A member has started working on the task
PENDING_APPROVAL: The member has submitted the task for review
COMPLETED: An approver has approved the submission

Tasks can also be CANCELLED at any point by a member with the appropriate permission.

Note: If a submission is rejected, the task returns to IN_PROGRESS so the member can try again.

Assigning Tasks

Tasks can be assigned to a specific member during creation or edited later. Members with the tasks.assign permission can assign tasks to anyone in the household. Unassigned tasks can be picked up by any member.

Submitting Completions

When you finish a task, submit it for approval. The task moves to PENDING_APPROVAL status and appears in the approval queue. Depending on your household's approval mode:

Admin Approval: A member with approval permissions reviews and approves it
Peer Confirmation: Any household member can confirm the completion
Self-Report: The task is automatically approved upon submission

Recurring Tasks

Recurring tasks automatically generate new task instances on a schedule. Supported frequencies:

Daily: A new task every day
Weekly: A new task every week on the same day
Biweekly: A new task every two weeks
Monthly: A new task every month on the same date

The task generator runs on a schedule (via a cron job) and idempotently creates tasks from templates, ensuring no duplicates. All dates are handled in UTC.

Tip: Recurring tasks are great for chores that happen on a regular basis, like taking out the trash every week or doing dishes daily.

Task Tags

Tags are household-scoped labels that help organize and filter tasks. Each tag has a name and an optional color. Tags are managed in the Settings page by members with the settings.manage permission.

Assign multiple tags to any task during creation or editing
Filter the task list by tags (inclusive OR — tasks matching any selected tag are shown)
Tags display as colored badges on task cards and detail views