---
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-01T06:20:56.632986+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
---

# 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