---
id: cb5e8814-f689-4de0-8854-823358706dec
type: solution
title: "Claude Scheduled Tasks: headless Claude Code on systemd timers"
tags: [claude-scheduled, systemd, automation, headless, claude-code, homelab, solution]
importance: 0.9
confidence: 0.8
created: "2026-03-01T06:20:55.075783+00:00"
updated: "2026-03-01T16:43:47.150565+00:00"
relations:
  - target: 62ee21e8-2b56-4d38-a73d-47e2724f08c6
    type: RELATED_TO
    direction: outgoing
    strength: 0.89
    edge_id: db026c0c-561b-4707-a639-e84fd30796bf
  - target: 39379120-896b-46cd-befa-b83d09d7556b
    type: RELATED_TO
    direction: outgoing
    strength: 0.83
    edge_id: 81f46fe3-13a8-47f5-9075-38593a064eab
  - target: 4edbf516-fe92-4e70-995a-266fe9f183ee
    type: RELATED_TO
    direction: outgoing
    strength: 0.81
    edge_id: 61b35eaa-20c9-4e0c-93c6-1718f38d53ad
  - target: b27fb831-811e-4103-b5f1-3c36d5b1ad20
    type: REQUIRES
    direction: incoming
    strength: 0.9
    edge_id: 57bef9f5-bad9-4111-b97e-75a7486bad71
  - target: 250d2fe0-5866-42f1-b83d-187b3a64fb84
    type: RELATED_TO
    direction: incoming
    strength: 0.9
    edge_id: 2cf0cf58-bef2-4ba9-a19d-05ce98b353c1
  - target: dfe48a70-b8ab-4bb5-a3d8-6116fa498168
    type: RELATED_TO
    direction: incoming
    strength: 0.85
    edge_id: 6e4d85b7-87e7-4a6e-b624-cf79679f0aaf
  - target: 057d7989-0465-413d-9a59-67e186133cec
    type: BUILDS_ON
    direction: incoming
    strength: 0.84
    edge_id: 81e81204-668e-4dd6-aa07-e63ef93e4b8c
  - target: c684a1ea-bdb6-4e4b-9416-e50e471221a0
    type: BUILDS_ON
    direction: incoming
    strength: 0.82
    edge_id: 1d8b07e5-4ad4-44d2-97c1-f103345b6b98
  - target: e6f9c92a-2964-4ffa-979c-700e7d23bed3
    type: RELATED_TO
    direction: incoming
    strength: 0.79
    edge_id: c795bfcc-99a7-43f4-bfc4-e071f0a91da9
---

# Claude Scheduled Tasks System

## Summary
Built a "Claude Cowork"-style scheduled task system using systemd timers and `claude -p` headless mode. Allows fully autonomous Claude Code sessions to run on a schedule without human interaction.

## Architecture

- **Universal runner:** `~/.config/claude-scheduled/runner.sh`
- **Per-task config directory:** `~/.config/claude-scheduled/tasks/<name>/`
  - `prompt.md` — task instructions
  - `settings.json` — model, budget, allowed tools
  - `mcp.json` — MCP server config for that task
- **Systemd template unit:** `claude-scheduled@.service`
- **Per-task timer files:** `claude-scheduled@<name>.timer`

## Key invocation flags
```
claude -p \
  --model sonnet \
  --max-budget-usd 0.75 \
  --output-format json \
  --no-session-persistence \
  --allowedTools <list> \
  --mcp-config <file> \
  --strict-mcp-config \
  --append-system-prompt <context>
```

## Critical notes
- Must `unset CLAUDECODE` before invoking `claude -p` inside any shell that may be a Claude session (nested session error otherwise)
- `--permission-mode bypassPermissions` cannot be used as root — run as non-root user
- `--max-budget-usd` is not an instant cutoff — can overshoot (set $0.25, spent $0.37)
- Results stored to cognitive-memory as workflow+episode
- Log rotation: keeps 30 logs per task in `~/.config/claude-scheduled/tasks/<name>/logs/`
- Global kill switch: create `~/.config/claude-scheduled/disabled` file to halt all tasks

## Gitea issue
claude-home#2