Scheduled Tasks

소개

Claude Code 세션 안에서 프롬프트를 일정 간격으로 자동 실행하려면 예약 작업을 사용하면 됩니다. 배포 상태를 주기적으로 확인하거나, PR을 모니터링하거나, 오래 걸리는 빌드를 다시 체크하거나, 나중에 해야 할 일을 상기시키는 용도로 사용할 수 있습니다.

/loop으로 반복 프롬프트 스케줄링하기

/loop 번들 스킬은 반복 프롬프트를 스케줄링하는 가장 간단한 방법입니다. 인터벌(interval)과 프롬프트를 함께 넘기면, Claude가 백그라운드에서 세션이 열려 있는 동안 동작하는 크론(cron) 잡을 설정합니다.

/loop 5m check if the deployment finished and tell me what happened

Claude는 인터벌을 파싱해 크론 표현식으로 변환하고, 해당 작업을 스케줄링한 뒤 주기와 작업 ID를 알려줍니다.

인터벌 문법

인터벌은 필수가 아닙니다. 명령 앞에 둘 수도 있고, 뒤에 둘 수도 있고, 아예 생략해도 됩니다.

지원하는 단위는 초(s), 분(m), 시간(h), 일(d)입니다. 크론은 최소 단위가 1분이므로, 초 단위는 가장 가까운 분 단위로 올림 처리됩니다. 7m이나 90m처럼 딱 나누어떨어지지 않는 인터벌은 가장 가까운 깔끔한 인터벌로 반올림되며, Claude가 어떤 값으로 조정했는지 알려줍니다.

다른 명령을 루프 돌리기

예약된 프롬프트 자체가 명령이나 스킬 호출이 될 수도 있습니다. 이미 만들어 둔 워크플로우를 반복 실행하고 싶을 때 유용합니다.

/loop 20m /review-pr 1234

작업이 실행될 때마다 Claude는 마치 사용자가 직접 입력한 것처럼 /review-pr 1234를 실행합니다.

단발성 리마인더

한 번만 실행되는 리마인더가 필요하다면 /loop 대신 자연어로 설명하면 됩니다. Claude가 단발성(single-fire) 작업을 예약하고, 실행이 끝나면 자동으로 삭제합니다.

remind me at 3pm to push the release branch

in 45 minutes, check whether the integration tests passed

Claude는 크론 표현식을 사용해 특정 시와 분에 맞춰 실행되도록 시간을 고정하고, 언제 실행될지 알려줍니다.

예약 작업 관리하기

Claude에게 자연어로 예약 작업을 나열하거나 취소해 달라고 요청할 수 있습니다.

what scheduled tasks do I have?

cancel the deploy check job

내부적으로 Claude는 다음 도구들을 사용합니다.

각 예약 작업에는 CronDelete에 넘길 수 있는 8자 길이의 ID가 부여됩니다. 하나의 세션에는 최대 50개의 예약 작업을 동시에 둘 수 있습니다.

예약 작업이 실행되는 방식

스케줄러는 1초마다 실행 예정인 작업이 있는지 확인하고, 해당 작업을 낮은 우선순위로 큐에 넣습니다. 예약된 프롬프트는 Claude가 응답을 생성하는 중간이 아니라, 사용자와의 턴 사이에 실행됩니다. 작업 실행 시점에 Claude가 다른 요청을 처리 중이라면, 그 요청이 끝난 뒤에 프롬프트가 실행됩니다.

모든 시간은 사용자의 로컬 타임존 기준으로 해석됩니다. 예를 들어 0 9 * * * 같은 크론 표현식은 UTC가 아니라 Claude Code를 실행 중인 환경의 현지 시간 기준으로 오전 9시를 의미합니다.

지터(Jitter)

모든 세션이 같은 시각에 동시에 API를 호출하는 상황을 피하기 위해, 스케줄러는 실행 시각에 작은 결정론적 오프셋을 더합니다.

• 반복 작업: 주기의 최대 10%까지 늦게 실행될 수 있으며, 지연 상한은 15분입니다. 예를 들어 매시간 실행되는 작업은 :00에서 :06 사이에 실행될 수 있습니다.
• 단발성 작업: 정시(:00)나 정각 30분(:30)에 맞춰진 작업은 최대 90초 일찍 실행될 수 있습니다.

이 오프셋은 작업 ID로부터 계산되므로, 같은 작업이라면 항상 동일한 오프셋이 적용됩니다. 실행 시각이 정확히 중요하다면 :00이나 :30이 아닌 분(예: 3 9 * * *)을 사용하면 단발성 지터가 적용되지 않습니다.

3일 후 자동 만료

반복 작업은 생성된 지 3일이 지나면 자동으로 만료됩니다. 만료 시점에 한 번 더 실행된 뒤 스스로 삭제되어, 깜빡 잊은 루프가 무한히 돌아가는 일을 방지합니다.

3일보다 더 오래 가는 반복 작업이 필요하다면 만료 전에 작업을 취소 후 다시 만들거나, Desktop scheduled tasks를 사용하세요.

크론 표현식 참고

CronCreate는 표준 5필드 크론 표현식을 받습니다: minute hour day-of-month month day-of-week

모든 필드는 와일드카드(*), 단일 값(5), 스텝(*/15), 범위(1-5), 콤마로 구분된 리스트(1,15,30)를 지원합니다.

요일 필드는 일요일을 0 또는 7로, 토요일을 6으로 지정합니다. L, W, ? 같은 확장 문법이나 MON, JAN 같은 이름 별칭은 지원하지 않습니다.

day-of-month와 day-of-week 둘 다 제한된 값이 설정되어 있는 경우, 둘 중 하나라도 일치하면 해당 날짜에 매칭된 것으로 간주합니다. 이는 표준 vixie-cron 동작과 같습니다.

비활성화

환경 변수에 CLAUDE_CODE_DISABLE_CRON=1을 설정하면 스케줄러를 완전히 비활성화할 수 있습니다. 이 경우 크론 관련 도구와 /loop는 사용할 수 없게 되고, 이미 예약된 작업도 더 이상 실행되지 않습니다.

사용 가능한 모든 비활성화 플래그 목록은 Environment variables에서 확인하세요.

제한 사항

세션 단위 스케줄링에는 다음과 같은 본질적인 제약이 있습니다.

• 작업은 Claude Code가 실행 중이면서 대기 상태일 때만 실행됩니다. 터미널을 닫거나 세션이 종료되면 모든 작업이 취소됩니다.
• 놓친 실행을 "밀어주기" 하지 않습니다. 작업이 예정된 시각에 Claude가 바쁘면, 다시 대기 상태가 되었을 때 한 번만 실행되며, 놓친 인터벌 수만큼 여러 번 실행되지는 않습니다.
• 재시작 후에는 작업이 유지되지 않습니다. Claude Code를 재시작하면 세션 단위 예약 작업은 모두 초기화됩니다.