Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Routines

A routine is a prompt Kimaki runs on a schedule: once at a future time, or again and again on a cron expression. The bot 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 a kimaki send command. It accepts a one-time UTC ISO timestamp (ending in Z) or a cron expression:
# 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.
The Kimaki bot must run on the machine that owns the channel. It stores the routine in its SQLite database and checks for due routines about every 5 seconds. If a cron routine misses runs while the bot is off, it runs once when the bot starts again.
With --channel (or --project), each run starts a new thread. With --thread (or --session), each run sends the prompt into that existing thread, shown as » routine #N: <prompt>.

Flagship example: a morning email digest

The pattern that makes routines shine: a morning email digest you can act on from Discord.
cron 0 7 * * * │ ▼ ┌─────────┐ ┌──────────┐ ┌───────────┐ │ read │ ───▶ │ post │ ───▶ │ you reply │ │ inbox │ │ digest │ │ (mark) │ └─────────┘ └──────────┘ └───────────┘
Schedule a routine that reads your inbox each morning with a CLI like Zele (a multi-account email and calendar CLI) and posts a summary:
kimaki 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 the prompt as a new thread in the channel. --notify-only needs --channel or --project, not a thread:
kimaki send --channel <channel-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 routine read and update a markdown file in the repo each run.
Most other send flags (--notify-only, --worktree, --base-branch, --cwd, --name, --agent, --model, --user, --permission) work with --send-at. Two do not:
  • --wait: the routine runs in the future.
  • --file: put the file in the project and name it in the prompt.
With --worktree, each run gets a fresh worktree with its own name.
Pass --user when someone should see the thread in Discord. Omit it for quiet autonomous work so the thread stays out of the sidebar. Clear a stored user later with kimaki routine edit <id> --user ''.

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:
#!/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:
pnpm add -g crisp-cli crisp-cli config --token '<crisp-mcp-token>'
Then schedule the check every five minutes:
kimaki 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 routine prompt under a ## Pre-run command output heading. Any other exit code skips that occurrence. Stderr goes to the Kimaki log. A pre-run command is stopped after 10 minutes.
Routines do not overlap by default. If the session of the last run is still active, a cron routine skips that occurrence and runs again at the next scheduled time. A one-time routine waits until the last session is done. Add --allow-concurrency only when parallel runs are safe.

Managing routines

kimaki routine list kimaki routine edit <id> --prompt 'new prompt' [--send-at 'new schedule'] \ [--agent <name>] [--model <provider/model>] [--pre-run 'command'] \ [--allow-concurrency true|false] [--user '<discord-user-id>'] kimaki routine edit <id> --user '' kimaki routine run <id> kimaki routine delete <id>
kimaki routine list shows planned, running, and failed routines. An empty string in routine edit clears a value. routine run starts a routine now, outside its schedule. Routines were called scheduled tasks before; the old kimaki task commands still work.
The /routines slash command lists the server's routines in Discord. Each routine has a Run now button and a Delete button. For the full kimaki send reference and CI usage, see CI & Automation.