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

Sleeping Sessions

An agent can put itself to sleep and wake up later in the same thread. Use it to wait for a deploy, a nightly build, a support reply, or a specific date. No tokens are used while it waits, and you do not need to remember to poke it.
The agent runs kimaki sleep in its shell, the session goes idle, and Kimaki wakes it when the time comes.
  agent runs kimaki sleep         Kimaki checks every 5s         same session resumes
            │                               │                               │
            ▼                               ▼                               ▼
  ┌────────────────────┐  writes  ┌────────────────────┐   due    ┌────────────────────┐
  │ session goes idle  │ ───────► │ wake row in SQLite │ ───────► │ wake message in    │
  │ no tokens used     │          │ survives restarts  │          │ the same thread    │
  └────────────────────┘          └────────────────────┘          └────────────────────┘

Asking for a sleep

Say it in the thread. The agent runs the command itself:
deploy is running, check back in 2 hours and confirm it went green
wait until tomorrow 9am UTC, then summarize what changed overnight
The command takes either --duration or --until, never both:
kimaki sleep --duration 2h --reason 'waiting for the deploy'
kimaki sleep --until 2030-01-01T09:00:00Z --reason 'nightly build'
OptionMeaningExamples
--durationRelative wait30m, 2h, 1d
--untilAbsolute UTC time2030-01-01T09:00:00Z
--reasonWhy it waits, shown on wakewaiting for the deploy
--until must be UTC and end with Z. Convert from your local time before you ask for a specific time.

Waking up

When the time comes, Kimaki shows a wake line in the same thread and the session continues with its full history:
-# Woke after sleeping until 2030-01-01 09:00 UTC. Reason: waiting for the deploy
The agent gets a message that starts with Woke after sleeping until and tells it to continue the work it waited for. The wake is a new turn on the same session, so the agent remembers everything from before the sleep.

It survives restarts

The wake time is stored in SQLite, not in memory. A restart of Kimaki or of the machine does not lose a pending sleep. When the bot runs again, a due sleep fires.
If a wake fails, Kimaki tries again every 30 seconds, up to 5 times. Each wake has a fixed ID, so a retry never wakes the same session twice.

Cancelling a sleep

Send any message in the thread and the pending sleep is cancelled. The agent handles your new message, and no wake comes later. If it still needs the later wake after it answers, it runs kimaki sleep again with the original --until time.
Most input cancels a sleep, not only chat messages: /queue, /abort, ! shell commands, OpenCode slash commands, button clicks, and prompts sent with kimaki send.
A new sleep replaces the pending one. Each session has at most one pending sleep.
The /btw command does not cancel a sleep. It forks your question into a side thread, and the sleeping thread keeps waiting.

Sleep vs routines

Both wait for the future, but they are different:
kimaki sleep--send-at
Who starts itThe agent, during a conversationYou or the agent, from the CLI
What resumesThis session, with full contextA new prompt
RepeatsNo, one timeCron supported
Best for"check back after the deploy"digests, reminders, recurring jobs
Use sleep when the current conversation must continue later. Use routines when fresh work must start on a timer.

Limits

  • The wake always goes to the main session of the thread, also when a subagent runs the command.
  • Kimaki checks for due wakes about every 5 seconds, so very short sleeps can be a little late.
  • The agent must run kimaki sleep last, after its text, and then stop. The command output is not a wake. Work continues only after the wake message.
  • If no thread owns the session when the wake is due, the wake is dropped.