Tasks

Task definitions live in .downcity/task/<taskId>/task.md.

Minimal task example

---
title: Daily Repo Check
when: "0 9 * * 1-5"
description: Run tests and summarize issues
sessionId: telegram-chat-123456
status: enabled
kind: agent
---

Run tasks, write the final output body to `output.md`, and write a summary to `result.md`.

Result Delivery

• Task runs write artifacts under .downcity/task/<taskId>/<timestamp>/.
• By default, the final result body is sent back to the chat bound to sessionId.
• sessionId decides where the task result returns; it is not an authentication identity.

Directory layout

.downcity/task/
  <taskId>/
    task.md
    <timestamp>/
      run.json
      output.md
      result.md
      dialogue.md

Common commands

city task list
city task create --title "Daily check" --description "Run tests" --session-id telegram-chat-123 --when "0 9 * * 1-5" --activate
city task run daily-check
city task update daily-check --when "@manual"
city task disable daily-check

Status

• enabled: scheduled
• paused: defined but not scheduled
• disabled: disabled

Time Semantics

• Cron expressions are interpreted in the local timezone of the runtime process. For example, when the runtime timezone is Asia/Shanghai, 0 13 * * * means 13
  Beijing time every day.
• time:<ISO8601> one-shot triggers must include an explicit timezone, such as time:2026-03-08T10:30:00+08:00.
• Proxies may affect IP-based location detection, but they do not change the machine timezone. To change cron semantics, change the system timezone or TZ for the runtime process.

Runtime requirement

Scheduling only works with a running runtime (typically city agent start).