Claude Code Hooks and Scheduled Routines: Handing Off the Start Button

Everything you've built so far, CLAUDE.md, skills, subagents, shares one thing in common: you had to type something to start it. Open a session and CLAUDE.md gets read. Type a slash command and a skill runs. Ask for a delegation and a subagent moves. Automatic as it sounds, the start button was always in a human's hands. Last lesson got you as far as splitting work off to run elsewhere. Today's about letting go of that start button itself. Just here for the automation, not the theory? This lesson alone covers it. If you found this lesson searching for a result rather than the word "hook," that's already covered in Lesson 1, so let's go straight to the result here.

Hook

A hook is a custom shell command that runs automatically at a specific point in Claude Code's lifecycle. It fires on a defined event, after editing a file, when opening a new session, when sending a notification, so a specific action always happens instead of Claude deciding case by case whether to run it.

What a hook is: a command that runs on an event

The official docs currently list more than 30 hook events. You don't need to memorize all of them, just get a feel for the handful that come up most.

This is a list that grows and shifts release to release. This lesson reflects what the official docs showed as of August 22, 2026, so if you're reading it much later, check the current event list against the docs again.

Where you register a hook decides its scope, the same logic as CLAUDE.md and skill locations.

Under each event, matcher narrows the scope further. Add matcher: "Edit|Write" under PostToolUse, for example, and the hook only fires when a file-editing tool runs, staying quiet for Bash or Read.

Setting up one hook

This blog's own repository has a real SessionStart hook wired into its .claude/settings.json.

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "node scripts/handoff.mjs --hook", "timeout": 15 },
          { "type": "command", "command": "node scripts/i18n-sync.mjs --changed --hook", "timeout": 20 }
        ]
      }
    ]
  }
}

With matcher left empty, both scripts run for every case that fires SessionStart: opening a session fresh, resuming one, or running /clear or /compact. One checks whether a different working directory has left a handoff note for this repository; the other checks whether the Korean and English editions have drifted out of structural sync. Both only check, they don't touch any files, so even a misfire doesn't delete or break anything.

A hook you're setting up for the first time is safer starting in a spot like this. The official docs' own first walkthrough is similar: a hook that sends a desktop notification while Claude is waiting for input. Open ~/.claude/settings.json (a personal setting, so it won't touch any other project) and add this.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code is waiting for input\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

This is a macOS example; Windows and Linux each use a different notification command. The exact commands for each platform are laid out in the official docs linked under Sources below.

What a schedule is: automation that runs at a set time

If a hook is "when something happens," a schedule is "at a time I set." Claude Code offers scheduling three ways, and each comes with different conditions. The interval and plan values in the table are as of August 2026.

Want a report draft to pop up automatically at 9 a.m. on the first of every month, like this track's running scenario? Cloud routines are the right fit, since they run on Anthropic's cloud even with your computer off. Type /schedule in your terminal and describe it in plain language.

/schedule Draft the monthly report with report-researcher and monthly-report-draft at 9 a.m. on the first of every month

Claude asks you to confirm the recurrence, the repository, and the prompt, then saves it to your account. The official docs note that cloud routines are still in research preview, so behavior and limits may change, and that they run fully autonomously, with no permission-mode picker and no approval prompts mid-run. If /schedule isn't showing up in your command list, you might be signed in with an API key or organization authentication instead. This command only appears when you're signed in with a claude.ai subscription account.

If the material your report draft depends on lives on your own computer rather than in a repository, the situation changes. Cloud routines clone the repository fresh every run, so they can't touch local files at all. That's when you'd use the desktop app's scheduled tasks instead. From the sidebar, go to Routines and pick Local to create a scheduled task that runs directly on your computer, with the minimum interval down to 1 minute. It only runs while the desktop app is open and your computer is awake, though. A run missed while your computer was asleep gets caught up just once, the most recent one within the last 7 days, when the app reopens (as of August 2026). Miss six days of a daily job and it runs exactly once, the moment it wakes up.

If all you want is a short, tight repeat of a few minutes inside a session that's already open, /loop is the lighter option. It only runs while the session stays open and ends the moment you close it, but if it's still active when you reopen the session with --resume, it picks back up right where it left off. Choosing between the three comes down to two questions: does it need to run with your computer off, and does it need to touch files on your own computer. There's no combination where both are true.

Anything that runs on its own needs a safety net

Cloud routines' own documentation states this plainly: "runs as a full autonomous Claude Code cloud session. There's no permission mode picker, and no approval prompts during execution." Running without a person watching means you have to narrow, ahead of time, what it's even allowed to do. You choose repositories yourself when you set up a routine, but every connector already linked to your account gets included by default. The official docs recommend keeping only what a routine actually needs, for both repositories and connectors, and dropping the rest.

Hooks carry a similar trap. You can build a PermissionRequest hook that auto-approves permission prompts, and leave matcher empty or set it too broadly, like .*, and every permission prompt, file writes and shell commands included, gets silently auto-approved. The official docs explicitly warn to keep this matcher as narrow as possible. Desktop scheduled tasks' "always allow" option works the same way. Approve it once, and every run after that goes through without asking, so it's worth occasionally checking the details page to see exactly which tools you've auto-approved.

Which narrows down to one principle: automate up through the draft, but not the last, hard-to-undo step, publishing, sending, paying. This track's running scenario is built the same way. What shows up automatically on the first of every month is a report draft, not the email that actually goes out to the client. Leaving a spot where a person checks and presses the final button is the safer call.

My own first automation wasn't a hook in a settings file either. It was a relay chain built inside a skill. While bundling content marketing prep into a skill, I chained the steps together so that finishing one step moves straight to the next, and hitting a snag partway sends it back to redo the earlier step, letting the whole thing run untouched until a finished result comes out. The idea itself, do this the moment that finishes, is exactly the same as a hook. Only the location is different.