obsidian/wiki/concepts/claude-code-schedule-skill-account-type.md

title	aliases	tags	sources	created	updated
Claude Code — /schedule Skill Requires claude.ai Login Account	claude-code-schedule schedule-skill-auth launchd-claude-code cron-claude-code	claude-code scheduling launchd macos automation knowledge-base	daily/2026-04-24.md	2026-04-24	2026-04-24

Claude Code — /schedule Skill Requires claude.ai Login Account

The /schedule skill in Claude Code creates recurring remote agent triggers that run on a cron schedule. It requires a claude.ai login account — it does not work with API-only accounts (accounts authenticated purely via ANTHROPIC_API_KEY without a claude.ai web account). On macOS, the fallback for periodic automation is native launchd Launch Agents, which run shell commands on a schedule without requiring a Claude login.

Key Points

• /schedule requires a claude.ai account (browser login), not an API-only account — attempting it with API-only auth results in a failure or unsupported operation
• macOS launchd is the correct fallback: Launch Agent plist files in ~/Library/LaunchAgents/ with StartCalendarInterval for cron-like scheduling
• launchd persists across reboots, respects user session, and can run any shell command — including uv run python scripts/compile.py for knowledge base automation
• A weekly launchd job (e.g., Mondays 09:00) and a monthly job (1st of month, 09:00) are the two schedules needed for knowledge base report generation
• The launchd approach requires no Claude authentication — it runs independently as a macOS system service

Details

Why /schedule Doesn't Work for API Accounts

The /schedule skill stores trigger configurations against the authenticated user's claude.ai session. The underlying API for managing scheduled remote agents is tied to the web account identity, not the API key. Developers who use Claude Code primarily via the terminal with an ANTHROPIC_API_KEY (without having set up a claude.ai web session) cannot create or list scheduled triggers.

This limitation is documented in the skill's description: "Create, update, list, or run scheduled remote agents (triggers) that execute on a cron schedule." The agent execution model requires the claude.ai account to host the trigger state.

macOS launchd as Fallback

macOS Launch Agents (~/Library/LaunchAgents/) are the native equivalent of user-level cron jobs. They are more robust than cron: they survive reboots, support calendar-based scheduling, and log to the system log.

Weekly report plist (~/Library/LaunchAgents/com.memory-compiler.weekly-report.plist):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.memory-compiler.weekly-report</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>-c</string>
        <string>cd ~/.claude/memory-compiler && uv run python scripts/report-generator.py --weekly</string>
    </array>
    <key>StartCalendarInterval</key>
    <dict>
        <key>Weekday</key>
        <integer>1</integer>   <!-- 1 = Monday -->
        <key>Hour</key>
        <integer>9</integer>
        <key>Minute</key>
        <integer>0</integer>
    </dict>
    <key>StandardOutPath</key>
    <string>/tmp/memory-compiler-weekly.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/memory-compiler-weekly.err</string>
</dict>
</plist>

Monthly report plist — same structure with StartCalendarInterval using Day: 1 instead of Weekday: 1.

Loading / Managing launchd Jobs

# Load (activate) a job
launchctl load ~/Library/LaunchAgents/com.memory-compiler.weekly-report.plist

# Unload (deactivate) a job
launchctl unload ~/Library/LaunchAgents/com.memory-compiler.weekly-report.plist

# Check if loaded
launchctl list | grep memory-compiler

# Force-run immediately (for testing)
launchctl start com.memory-compiler.weekly-report

# View logs
tail -f /tmp/memory-compiler-weekly.log

The job must be loaded after creation and after each reboot (or set RunAtLoad: true if you want it to also run on load).

When to Use /schedule vs launchd

Scenario	Use	Why
claude.ai login account available	/schedule skill	Managed by Claude, visible in UI, no local config
API-only account	launchd (macOS) / cron (Linux)	No claude.ai auth required; runs locally
Tasks that need Claude Code itself	/schedule	Triggers a remote Claude agent
Tasks running a local script	launchd	No need for Claude; just shell commands
Cross-machine scheduling	/schedule	Stored in cloud, fires from anywhere

For knowledge base compilation and report generation (local Python scripts), launchd is the correct tool regardless of account type — the scripts don't need Claude Code to run them, they use the Claude API directly.

Related Concepts

• wiki/claude-code/scheduled-tasks — /loop, CronCreate/List/Delete tools, and the /schedule skill documentation
• wiki/concepts/memory-compiler-mac-migration — the migration session where the /schedule limitation was discovered
• wiki/claude-code/headless-cli — running Claude Code non-interactively, which also involves auth considerations

Sources

• daily/2026-04-24.md — Mac migration session: /schedule skill invoked but failed because account is API-only; launchd selected as alternative; weekly (Monday 09:00) and monthly (1st of month) launchd plists created for report-generator.py