Automate with chores

Learn how chores let agents run recurring work.

This guide shows how chores work, where they live, and how to manage them.

What are chores?

Chores are recurring jobs for an agent.

A chore has an input and a few fields. The input tells the agent what to do on every run. Fields identify, display, schedule, and manage the chore. Most fields are optional or managed by the runtime.

Field	Optional?	Meaning
`schedule`	No	RRULE string used to schedule the chore.
`title`	Yes	Optional display title.
`id`	Yes	Auto-generated id.
`state`	Yes	Chore state: `active`, `inactive`, or `archived`.

Chores are usually stored as Markdown files in the agent home, under ${TOOLANG_ROOT}/agents/<agent>/chores/. Root-scoped chores are not supported yet.

In a Markdown chore, fields go in the frontmatter, and the input goes in the body:

---
schedule: "FREQ=HOURLY;INTERVAL=6"
title: Check stale PRs
---
 
Check stale pull requests and summarize blockers.

Chores are simple Markdown files. You can edit them directly with your favorite editor or manage them with the CLI.

Create chores

Use these commands to create, edit, and inspect chores.

Here, alice is the agent whose chores you are managing.

Command	Meaning
`toolang alice chore new`	Create a chore and open it in your editor.
`toolang alice chore edit <id>`	Open an existing chore.
`toolang alice chore list`	List current chores.

Retire chores

Use these commands to pause, restore, archive, or delete chores.

Again, alice is the agent whose chores you are managing.

Command	Meaning
`toolang alice chore pause <id>`	Temporarily retire a chore by setting it to `inactive`.
`toolang alice chore resume <id>`	Bring an inactive chore back by setting it to `active`.
`toolang alice chore archive <id>`	Retire a chore and move it into the archive.
`toolang alice chore restore <id>`	Restore an archived chore as `active`.
`toolang alice chore delete <id>`	Permanently delete an archived chore.

active chores are scheduled, inactive chores are kept but skipped, and archived chores are retired and hidden from the default list. Delete is destructive and only allowed for archived chores.

How chores run

Toolang checks chores during its pulse scan. When it finds a new or updated chore, it refreshes the chore’s schedule and treats it as due now if it is active.

Only active chores are scheduled. When an active chore is due, Toolang renders the chore input and starts a run on the chore’s thread. Run results are not written back to the chore definition; runtime status, run history, and results are stored separately.

If the rendered input is empty, Toolang skips that run and moves to the next scheduled time. After a chore is queued or skipped, Toolang calculates the next occurrence from its RRULE schedule.

Chore runs use the chore surface. If the agent defines a chore thunk, Toolang uses it. Otherwise, it falls back to the runtime default.