Guided Routines

How Guided Routines work

A Guided Routine is the pairing of three things:

• A fire URL + bearer token for a Claude.ai routine you created at claude.ai/code/routines.
• A daily schedule with one or more time slots (e.g. 08:00, 13:00, 17:30). Each slot has a mode that controls what context CloudClawer injects when it fires.
• A guided queueof agent tasks you've added — Claude works through them one at a time, gated by an optional process definition.

At each scheduled slot, CloudClawer POSTs to your routine's fire URL with optional injection text. Claude.ai spawns a fresh session, the session pulls one item off the guided queue, and CloudClawer logs the fire and resulting session in your dashboard.

Setting one up

Open Settings → Routinesin CloudClawer. You'll connect the routine in three steps:

1. Create a routine at claude.ai/code/routines and write the prompt Claude should run on each fire (e.g. "Check my open PRs and summarize what's blocked").
2. In the routine's Integrations panel, connect any tools the agent needs (Gmail, Google Calendar, GitHub, etc.).
3. Click Add trigger → API, save it, then paste the resulting fire URL + one-time bearer token into CloudClawer's Routines tab. CloudClawer stores the token server-side and never shows it back.

Daily schedule

Add up to several time slots per day (the cap depends on your plan). The UI accepts local time and converts to UTC for storage — slots fire at UTC time regardless of where you are.

Slot modes

Fire rate limits

Fires are capped per UTC day. The cap resets at 00:00 UTC and applies across manual test fires and scheduled fires combined.

Manual fires

Trigger a fire from the Routines tab, the CLI, or the API. Manual fires advance the guided queue (claiming the next queued task if no task is in progress).

POST /u/dkr/routine/fire
X-API-Key: YOUR_CLOUDCLAWER_KEY
Content-Type: application/json

{ "text": "Optional extra context appended to the routine prompt." }

The response contains the routine's response plus the sessionId and sessionUrl Claude.ai returned. You can poll the session URL or open it directly from the Routines page.

The guided queue

The Routines tab also surfaces the Agent Tasks queue. Each task can optionally name a process definition — if it does, CloudClawer creates a ProcessSessionwhen the task is fired and prepends the current state's question to the routine prompt.

Tasks move through three states: queued → in_progress → done. The agent can advance state by answering the process gate's question during the fired session.

Default process definition

Pick a default process from the Routines tab. Any task without an explicit process_definition_name falls back to it. Use this to put a guard rail (e.g. "ask permission before destructive actions") on every fire.

MCP for routines (/mcp/process)

Routines that need to read or update CloudClawer state — memory files, agent tasks, the current process session — should connect to /mcp/process instead of the general /mcp endpoint. It is a deliberately minimal MCP surface: container tools (bash), secrets, the proxy allowlist, and file-storage tools are categorically unreachable. The list of tools the routine can see is also tagged source="process" in audit logs, so a single grep separates routine-originated calls from chat or Claude Code calls.

Tools the endpoint exposes

The endpoint owns a hard-coded routine-safe whitelist. A process definition's allowed_tools field can further narrow this list, but cannot grant access to anything outside it.

Process scope resolution

On each request the endpoint picks one process definition to apply allowed_tools from, using the first match in this order:

1. ?process=<name> query parameter
2. X-CC-Process request header
3. The user's configured default process
4. None — falls back to the full routine-safe whitelist

Authentication

Same dual-auth as /mcp:

• X-Session-ID— the routine's Claude Code session ID. CloudClawer records this when it fires the routine, so the agent inside that session can authenticate without holding a long-lived key.
• X-API-Key — for routines that prefer a key, or for testing from the CLI.
• Authorization: Bearer — Clerk JWT for dashboard testing.

Example: narrow a process to memory + task_update

Restrict a process so its routine can only read memory and mark its task done, nothing else:

process_definition_upsert {
  "name": "morning-status",
  "initial": "report",
  "states": { "report": { "question": "Status posted?", "answers": { "yes": { "next": null, "action": "complete" } } } },
  "allowed_tools": ["memory_get", "memory_ls", "task_update", "process_step"]
}

Then point the routine at https://api.cloudclawer.com/mcp/process?process=morning-status — any attempt to call task_push or memory_findsimply won't appear in the agent's tool list.

Fire log

The 50 most recent fires are kept on the Routines tab. Each entry shows the timestamp, the source (manual or cron), the resulting Claude session ID, and any process sessions that hydrated alongside it.