claude-jobs

Scheduled, unattended Claude Code runs — driven by the CLI you already have logged in, so no ANTHROPIC_API_KEY is involved.

One command scaffolds the whole thing: a prompt, a hardened runner script, and a real scheduler entry (launchd, systemd or cron).

npx claude-jobs init morning-report \
  --skill ./playbooks/morning-report.md \
  --at 09:30 \
  --notify 'echo "$CLAUDE_JOB_MESSAGE" | mail -s "morning report" me@example.com'

npx claude-jobs run morning-report --dry-run   # see exactly what will happen
npx claude-jobs install morning-report          # hand it to the OS scheduler

If you have ever written the same claude -p wrapper script for the third time — the one with the explicit PATH, the random start delay, the summary file, the notifier — this is that script, generalized and tested.

Why

Claude Code is a real product with a real login. On the machine where you are already signed in, claude -p is a legitimate, non-interactive way to run work on your subscription. What that leaves you missing is everything around the call: schedulers start with an empty environment, unattended agents must never stop to ask a question, and a run nobody watches needs to report its own outcome.

claude-jobs is the boring wrapper that gets those details right, so the interesting part stays in your prompt.

Non-goals: this does not proxy, resell or wrap your subscription as an API for other tools. It runs the official CLI, as you, on your own machine. See docs/policy.md.

Claude Code also schedules work by itself now, in three different places. Read Do you need this? before installing — for a good share of daily jobs the built-in answer is the better one.

Install

npm install -g claude-jobs   # or just use npx claude-jobs
claude-jobs doctor           # safe-to-paste checks + a direct bug-report form link

Requires Node 18.17+, Claude Code installed and logged in (claude auth login) as the same user that will run the jobs.

Upgrading

Upgrading the package does not touch jobs you already created. run.sh is generated once, at init, and every job keeps the copy it was born with — so a fix that lands in the runner reaches new jobs only, until you say otherwise.

install regenerates it:

npm install -g claude-jobs@latest
claude-jobs list                       # the names you have
claude-jobs install <name>             # rewrites run.sh from the current template

That is the whole upgrade path, and it is safe to repeat — install is what you already run to register a job, and re-running it rewrites the runner and the scheduler unit from your existing job.json. Your prompt is not touched.

What it does not do is migrate job.json. A field added after your job was created is simply absent, and the runner falls back to that field's default. Concretely, for the one field where that is visible today: a job created before 0.1.6 has no recorded --log-max-bytes, so re-running install gives it the 5 MiB default and its log starts rotating. Keep the old append-forever behaviour with --log-max-bytes 0 at init, or by editing LOG_MAX_BYTES in the job's run.sh.

Commands

Useful init flags: --skill, --task, --prompt-file, --at HH:MM, --jitter, --workdir, --scheduler, --model, --precheck, --notify, --permission-mode. Run claude-jobs help for the full list.

What people run

A job earns its place when the work repeats, needs judgement rather than just a command, and produces something short enough to read over coffee. The five that pay off fastest:

• Dependency and CVE triage. Run the audit, then separate what actually reaches your code from what sits in a devDependency nothing calls, and open a PR for the safe patch bumps. The sorting is the value — listing every advisory is what you already ignore.
• Morning error triage. Read overnight errors, group them, and say which ones deserve attention. A dashboard counts them; this one interprets them.
• CI flake triage. Read the day's failed runs, group by cause, name the tests that failed for reasons unrelated to the change. A week of this gives you a ranked flake list instead of a feeling.
• Docs drift. Compare the docs against the code and open a PR for what diverged — renamed flags, examples that no longer run. Nobody wants this job; an agent never gets bored of it.
• A digest with your taste in it. Read the sources you chose and keep only what touches what you are working on now. The filter is what makes it different from an RSS reader.

claude-jobs init dep-triage --skill ~/playbooks/deps.md --at 02:30 \
  --workdir ~/src/api \
  --precheck 'git -C ~/src/api fetch --quiet' \
  --notify 'gh issue comment 42 --body "$CLAUDE_JOB_MESSAGE"'

More ideas — release notes, issue triage, cost anomalies, backup verification, competitor watch — plus the jobs that are a bad fit and why: docs/use-case-ideas.md.

What a job looks like on disk

~/.claude-jobs/
├── jobs/<name>/job.json      # the declaration
├── jobs/<name>/prompt.md     # what the agent is told — edit this freely
├── jobs/<name>/run.sh        # generated runner, yours to modify
├── logs/<name>.log           # stream-json, every step as it happens
└── state/<name>-summary.md   # the agent's own report, written last

Nothing is hidden in a database. Delete the directory and the job is gone.

The decisions baked into the runner

These are the parts that are easy to get wrong once and then debug for a week:

• Explicit environment. Schedulers do not load your shell profile. PATH, HOME and the absolute path to claude are written into the script.
• The prompt is a pointer. It names a skill or runbook file rather than embedding the logic, so behaviour changes without touching the scheduler.
• Unattended means unattended. The prompt tells the agent never to wait for an answer, and to park human decisions in writing instead of blocking.
• --permission-mode bypassPermissions. A headless run cannot approve anything. Override with --permission-mode if you want a stricter mode.
• --output-format stream-json --verbose. Steps land in the log as they happen instead of buffering until the end.
• Preconditions before spending a session. --precheck runs a cheap command first; if it fails, the run is skipped and reported rather than started into a broken environment.
• Random start jitter. Firing at the same second every day is a machine rhythm, and staggering also keeps several jobs off the same usage-limit cliff.
• Delivery is separate from logging. The agent writes a summary file as its last step; the runner delivers that file through --notify. No summary means the run is reported as failed, with the exit code.
• State lives in files. Each run is a fresh process; continuity comes from whatever the skill writes down.

Details and the reasoning behind each one: docs/design.md.

Beyond a laptop

The same "subscription instead of API key" idea shows up in a few officially supported places — GitHub Actions with claude_code_oauth_token, the Agent SDK authenticating as your account, and chat gateways that execute turns through the local CLI. Where each one fits, and where the line is: docs/use-cases.md.

Answering a chat message instead of a schedule

A scheduled job and a chat bot are the same substrate with a different trigger. OpenClaw is a self-hosted gateway that connects Zalo, Telegram, Slack and friends to an agent, and it can run every turn through your logged-in CLI — no API key in the config at all:

{
  "agents": {
    "defaults": {
      "model": { "primary": "claude-cli/claude-sonnet-5" },
      "cliBackends": { "claude-cli": { "command": "/opt/homebrew/bin/claude" } },
      "agentRuntime": { "id": "claude-cli" }
    }
  }
}

A ready-to-run script that merges this into an existing gateway config, with a backup and a dry run, is in examples/openclaw/:

node examples/openclaw/apply-claude-cli-backend.mjs            # show the diff
node examples/openclaw/apply-claude-cli-backend.mjs --write    # apply it

The full walkthrough — how a turn executes, why the model list must not contain a direct-API model, and what a long-running gateway does differently from a one-shot job — is in docs/openclaw.md.

Run both and you cover the two halves: the gateway answers when someone asks, claude-jobs acts when nobody does.

Do you need this?

Often not. Claude Code ships three ways to schedule work, and they cover most of what people reach for a wrapper script to do. Checked against the docs on 2026-08-18: