Scheduled Tasks

Kimaki can run a prompt on a schedule: once at a future time, or repeatedly on a cron expression. This turns the bot into an autonomous worker that wakes up, does a job, and posts the result as a Discord thread you can reply to.

Scheduling with `--send-at`

Add --send-at to any kimaki send command. It accepts a one-time UTC ISO timestamp (ending in Z) or a cron expression:

12345678# One-time: run at a specific UTC time
kimaki send --channel <channel-id> --prompt 'Review open PRs' \
  --send-at '2026-03-01T09:00:00Z'

# Recurring: every Monday at 9am UTC
kimaki send --channel <channel-id> \
  --prompt 'Run the test suite and summarize failures' \
  --send-at '0 9 * * 1'

All scheduling is in UTC. One-time dates must end with Z, and cron expressions fire in UTC too. Convert from your local time before scheduling.

Flagship example: a morning email digest

The pattern that makes scheduled tasks shine: a morning email digest you can act on from Discord.

  cron 0 7 * * *
       │
       ▼
  ┌─────────┐      ┌──────────┐      ┌───────────┐
  │ read    │ ───▶ │ post     │ ───▶ │ you reply │
  │ inbox   │      │ digest   │      │ (mark)    │
  └─────────┘      └──────────┘      └───────────┘

Schedule a task that reads your inbox each morning with a CLI like Zele (a multi-account email and calendar CLI) and posts a summary:

123kimaki send --channel <channel-id> \
  --prompt 'Use the zele CLI to read my unread emails. Post a concise digest grouped by sender and importance. List the message IDs so I can act on them.' \
  --send-at '0 7 * * *'

When the digest lands as a thread, reply to it to resume the work: "mark the GitHub ones as read and unsubscribe from the newsletters." The agent runs the corresponding zele commands. The whole loop, read then act, happens from one Discord thread.

Notify-only reminders

For a reminder that should not start an AI session, add --notify-only. It posts a thread you can reply to later:

123kimaki send --session <session-id> \
  --prompt 'Reminder: <@user-id> the staging API key created today expires 2026-06-01. Renew it before it breaks prod.' \
  --send-at '2026-05-28T09:00:00Z' --notify-only

Make reminder prompts detailed: the future reader has no context, so include what, when, why, and the exact action needed.

Other recurring patterns

Weekly QA — run the full test suite, summarize failures, mention a user only if review is needed.
Maintenance cron — rotate secrets, check dependency updates, clean stale branches on a 0 9 1 * * monthly schedule.
Project memory — have the task read and update a markdown file in the repo each run.

All other send flags (--notify-only, --worktree, --agent, --model, --user) work with --send-at. The exception is --wait, which is incompatible since the task runs in the future.

Run only when needed

Use --pre-run to run a shell command in the project directory before a scheduled occurrence starts. This example uses crisp-cli to start a support session only when Crisp has unread customer messages.

Create scripts/should-run-support.ts:

12345678910111213141516171819202122232425#!/usr/bin/env bun

import { $ } from 'bun'

type Conversation = {
  session_id: string
  unread?: { operator?: number }
  preview_message?: {
    from?: string
  }
}

const output = await $`crisp-cli list_website_conversations`.text()
const response = Bun.YAML.parse(output) as { items?: Conversation[] }
const requests = (response.items ?? []).filter((conversation) => {
  return (
    (conversation.unread?.operator ?? 0) > 0 &&
    conversation.preview_message?.from === 'user'
  )
})

const sessionIds = requests.map((conversation) => conversation.session_id)
if (sessionIds.length === 0) process.exit(1)

console.log(Bun.YAML.stringify({ sessionIds }))

The unread operator count means the support team has not read the message. The from: user check excludes operator replies. Install and configure the CLI once before scheduling:

12pnpm add -g crisp-cli
crisp-cli config --token '<crisp-mcp-token>'

Then schedule the check every five minutes:

1234kimaki send --channel <channel-id> \
  --send-at '*/5 * * * *' \
  --pre-run 'bun scripts/should-run-support.ts' \
  --prompt 'Read the Crisp session IDs in the pre-run output. Use crisp-cli to inspect each conversation and draft a support reply.'

An exit code of 0 starts the session. Kimaki appends the command's stdout to the task prompt. Any other exit code skips that occurrence. Stdout and stderr are also written to the Kimaki log.

Scheduled tasks do not overlap by default. If one occurrence still has an active OpenCode session, Kimaki skips the next occurrence and checks again at the following scheduled time. Add --allow-concurrency only when parallel runs are safe.

Managing tasks

1234kimaki task list
kimaki task edit <id> --prompt "new prompt" [--send-at "new schedule"] \
  [--pre-run "command"] [--allow-concurrency true|false]
kimaki task delete <id>

The /tasks slash command lists scheduled tasks in Discord with cancel buttons. For the full kimaki send reference and CI usage, see CI & Automation.