Scheduling

Letta Code can schedule prompts for a specific agent conversation. Use letta cron to register tasks, then keep letta server running so the connected environment can execute them.

This is a server-mode feature. It does not run in the standard interactive terminal session by itself.

Scheduled tasks are listener-backed. They only execute while a remote environment is connected with letta server.

Before you use it

• Start letta server and keep it running.
• Treat this as lightweight automation attached to a live environment, not a fully managed hosted scheduler.

Choose the right scheduling model

Use case	Best fit	Why
Run scheduled work on the same machine that has your files, tools, and shell access	Letta Code scheduling	Uses letta cron plus letta server to fire prompts into a real conversation
Run repeated stateless prompts from cron, CI, or shell scripts	Headless mode	Simple shell automation around letta -p

Quick start

Start a remote environment:

letta server --env-name "work-laptop"

In another terminal, add a recurring task:

letta cron add \
  --agent agent-123 \
  --conversation default \
  --name "daily-review" \
  --description "Summarize recent code changes every morning" \
  --prompt "Review recent changes and summarize any issues." \
  --cron "0 9 * * *"

Use --every 1d for a once-daily task at local midnight. Use --cron when you need a fixed time of day like 9:00am.

List tasks for the agent:

letta cron list --agent agent-123

If no listener is active when you add the task, Letta Code still creates it, but warns that it will only execute once letta server is connected.

How it works

1. letta cron add stores a task in ~/.letta/crons.json.
2. letta server starts the in-process scheduler when the remote listener connects.
3. The scheduler checks active tasks every minute.
4. When a task matches, Letta Code enqueues the prompt into the target agent and conversation.
5. The connected environment executes the task with access to that machine’s files, shell commands, and tools.

If the agent is already busy when a task fires, the scheduled prompt waits in the conversation queue and runs after the current turn finishes.

Command reference

Use letta cron to create, inspect, and remove scheduled tasks.

Command	Description
letta cron add --name <name> --description <text> --prompt <text> --every <interval> [options]	Create a recurring task from a human-friendly interval like 5m, 2h, or 1d
letta cron add --name <name> --description <text> --prompt <text> --at <time> [options]	Create a one-time task for a time like "3:00pm" or "in 45m"
letta cron add --name <name> --description <text> --prompt <text> --cron "<expr>" [options]	Create a recurring task from a raw 5-field cron expression
letta cron list [--agent <id>] [--conversation <id>]	List tasks, optionally filtered by agent or conversation
letta cron get <id>	Show details for one task
letta cron delete <id>	Delete one task
letta cron delete --all --agent <id>	Delete all tasks for an agent

Required fields for add

• --name: short label for the task
• --description: longer summary of what the task is for
• --prompt: the prompt that will be sent when the task fires
• One schedule selector: --every, --at, or --cron
• --agent <id> unless LETTA_AGENT_ID is already set in the environment

Conversation selection defaults to LETTA_CONVERSATION_ID when available, or default otherwise.

Current behavior and limits

These constraints are important enough to know before you depend on the feature:

• Tasks only execute while letta server is connected.
• One-shot tasks that are more than 5 minutes late are marked as missed.
• Letta Code currently allows up to 50 active tasks per agent.
• --every 1d fires daily at local midnight. Use --cron for a fixed time of day.
• --at values are interpreted in your local timezone.
• Raw cron expressions are evaluated in the local timezone by default.
• All letta cron commands print JSON, so they work well in scripts and wrappers.

Examples

Daily review

letta cron add \
  --agent agent-123 \
  --name "daily-review" \
  --description "Review recent changes every morning" \
  --prompt "Review recent changes and summarize any issues." \
  --cron "0 9 * * 1-5"

One-time reminder

letta cron add \
  --agent agent-123 \
  --conversation default \
  --name "deploy-reminder" \
  --description "Remind me to validate staging before deploy" \
  --prompt "Check staging health, review recent failures, and summarize anything blocking deploy." \
  --at "in 45m"

Frequent recurring check

letta cron add \
  --agent agent-123 \
  --name "log-watch" \
  --description "Check logs every five minutes" \
  --prompt "Inspect the latest logs and flag anything unusual." \
  --every 5m

Troubleshooting

• My task never ran

  • Make sure letta server was connected when the schedule should have fired.
  • Run letta cron list --agent <id> and confirm the task is still active.

• My one-time task disappeared without running

  • If the listener was down for long enough, the task may have been marked as missed.

See also

• Remote environments
• Headless mode
• CLI reference