Cryochamber

Cryochamber is a hibernation chamber for AI agents (Claude, OpenCode, Codex, Pi, Kimi Code). It hibernates an agent between sessions and wakes it at the right time — not on a fixed schedule. The agent reads its plan, completes a task, and decides for itself when to wake next. That lets AI agents run tasks that span days, weeks, or even years, like interstellar travelers in stasis.

Why not cron?

Cron wakes on a fixed schedule, whether or not there is anything to do. Cryochamber hands the scheduling decision to the agent:

• It saves tokens. A cron-driven agent burns a full session on every tick, even when nothing has changed. A cryochamber agent sleeps until there is a reason to wake — a TODO it scheduled, or a message in its inbox.
• It saves your brain. With cron, a human has to guess the right schedule up front: too fast wastes money, too slow misses things. Here the agent reasons about the situation — a deadline that slipped, a review waiting on the author, a chess opponent’s pace — and picks its own next wake.
• It handles emergencies. When something demands attention, the agent can schedule a wake minutes out, and an inbox message can wake it immediately. Cron cannot speed up when it matters.

Get running in two minutes

Platform support: macOS and Linux only.

cargo install cryochamber
mkdir my-chamber && cd my-chamber
cryo init          # scaffold plan.md and cryo.toml (or let the make-plan skill guide you)
cryo start         # start the daemon, installed as an OS service
cryohub start      # open the printed dashboard URL in your browser

Then edit plan.md to describe the agent’s goal and tasks. Runnable example chambers (mr-lazy, chess-by-mail, and more) live in examples/chambers/ on GitHub.

Watch it work

cryohub start    # prints the local dashboard URL — open it in your browser

Cryohub is the local web dashboard: chamber status, message history, TODOs, notes, log tail, and lifecycle controls, plus a send widget to talk to the agent. For remote messaging from the web or your phone, bridge the chamber to Zulip with cryo-zulip.

What a chamber guarantees

• Every wake produces a visible message. If the agent exits without replying, the daemon writes a fallback message — a session is never silent.
• Every inbox message is answered. Even if the agent crashes mid-session, the sender still gets a reply.
• Every TODO is honoured. Failed sessions are rescheduled as visible retry attempts with exponential backoff.
• Nothing is consumed twice. Claimed messages and TODOs never silently become pending again.

Next

• How it works — a five-minute walkthrough: the chamber files and the session loop.
• CLI reference — every cryo, cryohub, cryo-agent, and cryo-zulip command.
• Configuration — every cryo.toml and cryohub.toml field.

How it works

A five-minute walkthrough of a chamber’s moving parts.

A chamber is just a directory

cryo init creates three files:

• plan.md — the agent’s mission: goal, tasks, and rules. The agent re-reads it at the start of every session.
• cryo.toml — chamber configuration: which agent command to run, session timeout, inbox watching. See Configuration.
• NOTES.md — the agent’s memory across sessions. It reads and appends to this file directly.

While the daemon runs, runtime state appears alongside them: logs, todo.json, and messages/inbox/ + messages/outbox/.

The plan is plain markdown

A chamber that watches a GitHub repo for new releases:

# Release watcher

## Goal
Tell me when acme/widgets publishes a new release.

## Tasks
1. Run `gh release list --repo acme/widgets --limit 1` and compare
   the version with the one recorded in NOTES.md.
2. If it changed: send me the release notes with `cryo-agent send`,
   then record the new version in NOTES.md.
3. Schedule the next check with `cryo-agent todo add` — every 2 hours
   on weekdays, once a day on weekends.
4. Hibernate with `cryo-agent hibernate --summary "..."`.

No code, no cron expression — the agent reads the situation (weekday vs. weekend here) and decides the next wake itself.

The session loop

daemon wakes agent        <- earliest TODO due, or inbox message
    │
    v
agent reads plan.md + NOTES.md
    │
    v
does the work
    │
    v
cryo-agent send "..."                    <- a visible message, never silent
    │
    v
cryo-agent todo add "..." --at <when>    <- declares the next wake
    │
    v
cryo-agent hibernate                     <- daemon sleeps until that wake
    │
    └────────────── back to the top ──────────────┘

One wake, one agent run, one return to sleep — that is a session:

1. The daemon wakes the agent when the earliest pending TODO comes due, or immediately when an inbox message arrives.
2. The agent reads plan.md and NOTES.md, then does the work.
3. It sends at least one visible message with cryo-agent send. If it exits without sending, the daemon writes a fallback message — a session is never silent.
4. It declares its own next wake with cryo-agent todo add "..." --at <time>. The daemon’s next wake is always the earliest pending TODO — no TODO, no wake.
5. It calls cryo-agent hibernate and exits. The daemon sleeps until the next trigger. hibernate --complete ends the plan for good.

Talking to the agent

Send a message from the terminal (cryo send "...") or the Cryohub dashboard. It lands in messages/inbox/ and — with the default watch_dirs — wakes the agent immediately. The agent’s replies appear in messages/outbox/ and in the dashboard’s message history.

Next

• CLI reference — every cryo, cryohub, cryo-agent, and cryo-zulip command.
• Configuration — every cryo.toml and cryohub.toml field.

CLI reference

All cryochamber binaries and their commands. For cryo.toml and cryohub.toml fields, see Configuration.

Every binary accepts --version (print the version and exit) and --help.

Operator CLI (cryo)

Run these from inside a chamber directory unless noted otherwise.

Hub (cryohub)

Agent IPC (cryo-agent)

These commands are used by the spawned AI agent to communicate with the daemon over a Unix socket. They are not the operator interface.

Zulip Sync (cryo-zulip)

Configuration

Each chamber is configured through a cryo.toml file in its directory. cryo init creates one with sensible defaults.

cryo.toml

# cryo.toml — cryochamber project configuration
agent = "opencode"               # Agent command (opencode, claude, codex, pi, kimi, ...)
max_session_duration = 3600      # Session timeout in seconds (0 = no timeout)
watch_dirs = ["messages/inbox"]  # Directories to watch for reactive wake ([] disables)
zulip_poll_interval = 5          # Zulip sync poll interval in seconds

# Provider environment injected into every agent session (optional).
[provider]
name = "anthropic"               # Display name, shown in `cryo status`
env = { ANTHROPIC_API_KEY = "sk-ant-..." }  # Env vars set when spawning the agent

The reply window is not configured here. How long a successful hibernate stays open for a follow-up message is chosen by the agent per hibernate via cryo-agent hibernate --linger <seconds> (omitted = 300 s, capped at 86400; 0 sleeps immediately). The session clock is suspended while a hibernate is parked and each follow-up round gets a fresh budget, so a generous linger can hold one session open well past max_session_duration.

[provider]

Cryochamber supports a single active provider profile. The [provider] table carries a display name and an env map of environment variables that are injected into every spawned agent session — this is where API keys for the agent’s model belong.

[provider]
name = "anthropic"
env = { ANTHROPIC_API_KEY = "sk-ant-...", OPENCODE_MODEL = "claude-sonnet-4-20250514" }

cryo status shows the provider name once one is configured.

Security: values under [provider].env are secrets. cryo init writes a chamber .gitignore that ignores .cryo/, but cryo.toml itself is not gitignored — if you commit or push the chamber, keep API keys out of version control. Either add cryo.toml to your own .gitignore, or leave the keys out of cryo.toml and export them in the environment before cryo start instead.

Legacy [[providers]] (deprecated)

Older configs used a [[providers]] array. It is still accepted for backward compatibility, but only the first entry is used — provider rotation was removed. Loading a config that uses [[providers]] prints a deprecation warning, and the next save rewrites it to the canonical single [provider] form. Migrate to [provider].

See cryohub.toml below.

cryohub.toml

Cryohub settings live in $XDG_CONFIG_HOME/cryo/cryohub.toml, or ~/.config/cryo/cryohub.toml if XDG_CONFIG_HOME is unset. The default local dashboard URL is http://127.0.0.1:8765. The dashboard’s New Chamber button creates chambers under the configured chamber_root, which defaults to ~/.cryo/chambers.

host = "127.0.0.1"
port = 8765
chamber_root = "/Users/alice/.cryo/chambers"

For project-owned chamber collections, set chamber_root to a project path such as /path/to/project/.cryo/chambers.

Override config from the command line

Flags passed to cryo start override cryo.toml for that session. The overrides are stored in timer.json (runtime state) and do not modify cryo.toml.

cryo start --agent claude
cryo start --max-session-duration 3600

Config vs. state