Markdown tasks

A markdown task is one file under schedule/ in the hub. The frontmatter says when it runs, which paths it may change and, optionally, which account it runs as. The body is instructions that the hub's own agent carries out unattended, with the same AGENTS.md, skills, knowledge, tools and model as chat.

When to use thisCopy Anchor Link

Use a markdown task for recurring work you can describe in a paragraph: a weekly summary, a nightly reconciliation, keeping knowledge in step with a repository. Use a code workflow when the steps must be exact, and a webhook trigger when an outside system should start the work.

Write a task end to endCopy Anchor Link

The example is a home goods retailer with four stock locations. Each night a count export lands in raw_data/counts/. On Monday morning a task writes a summary of the week.

---
schedule: "17 7 * * 1"        # Mondays at 07:17, server local time
timeout: 900                  # seconds per round
max_rounds: 3
write: ["output/counts/"]     # writable, not committed, while you test
---

Summarize last week's stock counts for the four store locations.

- Call `current_time` for today's date. The report file is
  `output/counts/week-<YYYY-MM-DD>.md`.
- Your state file records the date of the last report. If this week's
  report is already recorded, report DONE.
- List the exports under `raw_data/counts/` with `list_files` and read the
  ones from the last 7 days with `read_file`.
- For each location, write the net count change and the five items with
  the largest change. Name any location with no export this week at the top.
- Save the report with `write_hub_file`, then record today's date in the
  state file.
- You are done when the report is written and the state file is updated.

hubzoid doctor my-hub                                    # schedule.tasks: every file parses
hubzoid schedule list my-hub                             # cadence, next fire, last result
hubzoid schedule run my-hub weekly-count-summary --dry-run

hubzoid schedule run my-hub weekly-count-summary --timeout 300 --max-rounds 2

commit: ["output/counts/"]
push: true

FrontmatterCopy Anchor Link

Every task needs exactly one trigger, schedule: or on_webhook:. An agent task also needs a non-empty body. Keys not listed here are ignored.

A file is rejected when a trigger is missing or doubled, the cron has the wrong field count or never matches a real date, an integer is not positive, a path is absolute or contains .., push: true has no commit: paths, model: is empty, a run: list contains unquoted values, run_as: is not an email, publish_artifacts: or send_email: is not true or false or is set on a run: task, or an agent task has no body. A rejected file is skipped and every other task keeps running. hubzoid schedule list prints the problem and exits 1, hubzoid doctor fails schedule.tasks, and the Console lists it as an error. Files named README.md or starting with . are not tasks.

Cron and timeCopy Anchor Link

Each field accepts *, */N, a value, a range A-B, a stepped range A-B/N or a comma list of these. Values are numbers only, so write 1 for Monday, not MON. When both day of month and day of week are restricted, a day matches if either one matches, as in standard cron.

• Tasks run in the local time of the machine that runs the hub. In a container, that is the container's local time.
• The scheduler checks every 30 seconds and re-reads schedule/*.md each time, so edits apply without a restart.
• A new task anchors when the scheduler first sees it and first runs at its next future match. Use hubzoid schedule run to try it at once.
• After downtime, a task that missed one or more matches runs once on the first tick, not once per missed match. The number of slots it stood in for goes into its missed_log, kept for 31 days.
• A due task waits while the hub is answering chat and starts on a later tick.
• Markdown tasks run one at a time per hub.

Pick an off-minute such as 7 3 rather than 0 3. It keeps your task apart from the many jobs that start on the hour and makes logs easier to correlate.

How a run worksCopy Anchor Link

Each run is a loop of rounds. A round is one fresh agent session that receives a harness preamble, your body, and a carry note from the previous round. Fresh contexts let a large backlog be chunked across rounds instead of overflowing one session.

The preamble tells the agent that it runs unattended, where its state file is, which paths it may write, that failed tool results are failures, never to regress its state file, and its time budget. It ends with the finish protocol. The agent must end every round with exactly one of these lines:

STATUS: DONE — <one-line summary of what changed>
STATUS: CONTINUE — <what remains>

Hubzoid matches that line, case-insensitively, and the last one in the reply wins. A colon or hyphen after DONE also parses. Nothing else ends a run early.

A run ends as done, incomplete or error. Only error marks the run as failed in the Console. An incomplete run shows as succeeded, with incomplete in its result, and hubzoid schedule run exits 1 for it.

State and log filesCopy Anchor Link

<person> is a folder name derived from the account's email, so the same task run for two people never shares state. The run's own folder is always writable by the task. A folder from before 1.0.1, .hubzoid/schedule/<task>/, is kept as it was and used only by a legacy hub with no account configured. To carry its state over, copy state.json into the person's folder before their first run. Keep .hubzoid/ out of git. It is runtime state, not content.

Tools during a runCopy Anchor Link

The agent has the hub's usual tools (read_file, list_files, grep_data, knowledge and skill tools, hub tools and MCP servers) plus two that exist only in scheduled runs:

The agent cannot commit or push. Hubzoid does that itself after the run.

Publish and email resultsCopy Anchor Link

A task opts in to delivery in its frontmatter. The model cannot turn these tools on, and cannot change the owner or the recipient.

---
schedule: "7 7 * * 1-5"
run_as: priya@company.com
publish_artifacts: true
send_email: true
---

Write today's digest as an HTML file in your scratch folder, publish it,
and email me a link.

The artifact is private to that account until they share it from its viewer. Email uses the deployment's SMTP settings (HUBZOID_SMTP_*), or writes to a preview outbox with HUBZOID_EMAIL_DELIVERY=preview. The tool reports the delivery status. Only accepted means the SMTP server took the message, and previewed means it was written to the outbox and not sent. Tasks without these keys are offered nothing new.

Write, commit and pushCopy Anchor Link

• write: paths can be changed but are never committed. Use them while testing, then review the diff by hand.
• commit: paths are writable too. After a done run, Hubzoid stages and commits exactly those paths with the message schedule(<task>): <summary>. Changes elsewhere in the working tree, such as source clones under raw_data/ or local edits, are never swept in.
• A run that changed none of its commit: paths makes no commit and pushes nothing.
• With push: true, Hubzoid runs git pull --rebase and then git push, and retries the push once. A rebase conflict is aborted cleanly: the run is recorded as error, the commit stays local and nothing is pushed.

The hub can be the root of a repository or a folder inside a larger one. Set up the server once: the repository needs a remote and a tracking branch, git config user.name and user.email, and credentials that work without a prompt, such as a deploy key.

Run a command instead of the agentCopy Anchor Link

A task with run: executes a command in the hub folder and does not call the model. It shares the same schedule, queue, log, state and commit steps.

---
schedule: "41 1 * * *"
run: ["python", "scripts/export_counts.py", "--days", "1"]
timeout: 600
commit: ["output/exports/"]
---

Writes yesterday's count export. Documentation only.

A string such as run: "python scripts/export.py | gzip > output/exports/latest.gz" runs through the shell, so pipes and && work. A list runs without a shell. Exit code 0 is done and any other code is error. When timeout passes, the whole process group is stopped. The log keeps the last 4,000 characters of standard output and standard error. The script finds the account the run acts as in HUBZOID_RUN_AS, for information only. It gains no permission from it.

Run once with hubzoid schedule runCopy Anchor Link

hubzoid schedule run <hub> <task> [--timeout SECONDS] [--max-rounds N] [--model ID] [--dry-run]

A manual run ignores the cron and the chat gate. It is queued on the same one-at-a-time queue as scheduled runs, so it waits for a running one and never overlaps it. It uses the hub's configured model and appears in the run history with an id such as md:weekly-count-summary:manual-20260925T101500. A manual run of a webhook task claims no events. Exit codes: 0 done, 1 incomplete or failed, 2 no such task.

Enable, disable and pauseCopy Anchor Link

See Operating runs for pause, resume, cancel and troubleshooting.

AccessCopy Anchor Link

A markdown task runs as an ordinary account: run_as:, else HUBZOID_WORKFLOW_USER, else the owner recorded at setup. The resolution and its rules are in Workflows and schedules. hubzoid schedule list and the Runs as column in the Console show the account, or why the task cannot run. A run fails, with the fix in its error, when the account is missing or cannot be used, and never falls back to another person.

The task reaches a restricted tool only when that account holds the tool's permission, on a hub whose access is managed in the Console. Grant it with Edit access in the Console, or on the command line:

hubzoid grant priya@company.com <permission> my-hub

Grants made to the legacy identity workflow:md:<task> before 1.0.1 stay but are not used. A legacy hub with no account configured keeps running the task as workflow:md:<task>. Each round writes a usage row for the run's account, so its tokens and estimated cost appear on the agent's card on the Console's Agents page. See Restrict tools.

Next stepsCopy Anchor Link

Read this page as Markdown