Chore files

Chore files are recurring Markdown work items for one agent. The frontmatter stores scheduling metadata. The body stores the recurring work instruction sent to the agent when the chore is due.

Location

Active and paused chores live under the agent home:

${TOOLANG_ROOT}/agents/<agent>/chores/<id>.md

Archived chores move under an hourly UTC archive bucket:

${TOOLANG_ROOT}/agents/<agent>/archive/chores/<YYYYMMDDTHHZ>/<id>.md

Authored files can use a readable filename such as sync-issues.md. If the file is missing id, Toolang writes one when it scans the chore.

Markdown format

A minimal chore usually includes a title, schedule, and Markdown body:

---
title: Check stale PRs
schedule: FREQ=HOURLY;INTERVAL=6
---
 
Check stale PRs and report actionable items.

The explicit form is:

---
id: xy1234ab
title: Check stale PRs
state: active
schedule: FREQ=HOURLY;INTERVAL=6
---
 
Check stale PRs and report actionable items.

state: active is the default and can be omitted.

Frontmatter

Field	Required	Default	Meaning
`id`	no	generated on scan	Stable local chore id
`title`	no	derived from body or filename	Display title
`state`	no	`active`	File lifecycle
`schedule`	no	`FREQ=HOURLY;INTERVAL=1`	RRULE schedule

Unknown frontmatter fields are ignored by the current document model.

State and schedule

state controls whether the chore participates in scheduling:

State	Meaning
`active`	Scheduled when due
`inactive`	Kept on disk but skipped
`archived`	Retired and listed only through archived views

schedule is parsed as an RRULE string with dateutil.rrule.

---
title: Daily issue sync
schedule: FREQ=DAILY;BYHOUR=9;BYMINUTE=0
---
 
Sync newly assigned issues into local tasks.

Pausing a chore writes state: inactive. Resuming writes state: active. Archive a chore by setting state: archived or using the chore archive command.

`.too` format

Chores are not declared inside .too files. Toolang discovers Markdown files under chores/ and schedules them against the agent's normal .too program.

The chore input is rendered from the title and body, so a normal default thunk is enough:

agent.too

use service openhat/github
 
thunk:
  models = gpt-5
  services = github
  tools = service_use
 
  user:
    {{input}}

For a chore file like:

---
title: Check stale PRs
schedule: FREQ=DAILY;BYHOUR=9;BYMINUTE=0
---
 
Find stale open PRs and summarize the ones needing action.

the agent receives:

# Check stale PRs
 
Find stale open PRs and summarize the ones needing action.

Notes

Runtime output, run history, and scheduler state live in .runtime/runs.db; they are not appended to the chore body. Chore thread ids are runtime projections with the form chore_<id>.