스케줄에 따라 프롬프트 실행하기

/loop과 cron 스케줄링 도구를 사용하여 Claude Code 세션 내에서 프롬프트를 반복 실행하거나, 상태를 폴링하거나, 일회성 리마인더를 설정하세요.

예약 작업을 사용하면 Claude가 일정 간격으로 프롬프트를 자동으로 다시 실행합니다. 배포를 폴링하거나, PR을 모니터링하거나, 장시간 실행되는 빌드를 확인하거나, 세션 중 나중에 해야 할 일을 리마인드하는 데 활용할 수 있습니다.

작업은 세션 범위입니다: 현재 Claude Code 프로세스 내에 존재하며, 종료하면 사라집니다. 재시작 후에도 유지되고 활성 터미널 세션 없이 실행되는 영구 스케줄링은 데스크톱 예약 작업 또는 GitHub Actions를 참조하세요.

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

/loop 번들 스킬은 반복 프롬프트를 스케줄링하는 가장 빠른 방법입니다. 선택적 간격과 프롬프트를 전달하면, Claude가 세션이 열려 있는 동안 백그라운드에서 실행되는 cron 작업을 설정합니다.

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

Claude가 간격을 파싱하고, cron 표현식으로 변환한 후 작업을 스케줄링하며, 주기와 작업 ID를 확인해 줍니다.

간격 구문

간격은 선택 사항입니다. 앞에 붙이거나, 뒤에 붙이거나, 아예 생략할 수 있습니다.

형식	예시	파싱된 간격
앞쪽 토큰	/loop 30m check the build	30분마다
뒤쪽 every 절	/loop check the build every 2 hours	2시간마다
간격 없음	/loop check the build	기본값 10분마다

지원되는 단위는 초(s), 분(m), 시간(h), 일(d)입니다. 초는 cron이 1분 단위의 정밀도를 가지므로 가장 가까운 분으로 올림됩니다. 7m이나 90m처럼 해당 단위로 균등하게 나누어지지 않는 간격은 가장 가까운 깔끔한 간격으로 반올림되며, Claude가 선택한 값을 알려줍니다.

다른 명령어를 반복 실행하기

스케줄링된 프롬프트 자체가 명령어나 스킬 호출이 될 수 있습니다. 이미 패키징해 둔 워크플로를 다시 실행하는 데 유용합니다.

/loop 20m /review-pr 1234

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

일회성 리마인더 설정하기

일회성 리마인더의 경우, /loop 대신 자연어로 원하는 내용을 설명하세요. Claude가 실행 후 자동으로 삭제되는 단발성 작업을 스케줄링합니다.

remind me at 3pm to push the release branch

in 45 minutes, check whether the integration tests passed

Claude가 cron 표현식을 사용하여 실행 시간을 특정 분과 시에 고정하고, 언제 실행될지 확인해 줍니다.

예약 작업 관리하기

Claude에게 자연어로 작업을 나열하거나 취소하도록 요청하거나, 기본 도구를 직접 참조할 수 있습니다.

what scheduled tasks do I have?

cancel the deploy check job

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

도구	목적
CronCreate	새 작업을 스케줄링합니다. 5필드 cron 표현식, 실행할 프롬프트, 반복 여부를 입력받습니다.
CronList	모든 예약 작업의 ID, 스케줄, 프롬프트를 나열합니다.
CronDelete	ID로 작업을 취소합니다.

각 예약 작업에는 CronDelete에 전달할 수 있는 8자리 ID가 있습니다. 세션당 최대 50개의 예약 작업을 보유할 수 있습니다.

예약 작업의 실행 방식

스케줄러는 매초 실행 대상 작업을 확인하고 낮은 우선순위로 큐에 넣습니다. 예약된 프롬프트는 Claude가 응답 중일 때가 아니라, 사용자의 턴 사이에 실행됩니다. 작업 실행 시점에 Claude가 작업 중이면, 현재 턴이 끝날 때까지 프롬프트가 대기합니다.

모든 시간은 로컬 시간대로 해석됩니다. 0 9 * * *과 같은 cron 표현식은 UTC가 아니라, Claude Code를 실행하는 곳의 오전 9시를 의미합니다.

지터(Jitter)

모든 세션이 같은 시계 시각에 API를 호출하는 것을 방지하기 위해, 스케줄러는 실행 시간에 작은 결정론적 오프셋을 추가합니다:

• 반복 작업은 주기의 최대 10%까지 늦게 실행되며, 최대 15분으로 제한됩니다. 1시간 주기 작업은 :00에서 :06 사이 어디서든 실행될 수 있습니다.
• 정시 또는 30분에 스케줄링된 일회성 작업은 최대 90초 일찍 실행됩니다.

오프셋은 작업 ID에서 파생되므로, 같은 작업은 항상 같은 오프셋을 가집니다. 정확한 타이밍이 중요하다면 :00이나 :30이 아닌 분을 선택하세요. 예를 들어 0 9 * * * 대신 3 9 * * *을 사용하면 일회성 지터가 적용되지 않습니다.

3일 만료

반복 작업은 생성 후 3일이 지나면 자동으로 만료됩니다. 작업이 마지막으로 한 번 실행된 후 스스로 삭제됩니다. 이는 잊혀진 반복 작업이 얼마나 오래 실행될 수 있는지를 제한합니다. 반복 작업이 더 오래 지속되어야 한다면, 만료 전에 취소 후 재생성하거나, 영구 스케줄링을 위해 데스크톱 예약 작업을 사용하세요.

Cron 표현식 참조

CronCreate는 표준 5필드 cron 표현식을 허용합니다: minute hour day-of-month month day-of-week. 모든 필드는 와일드카드(*), 단일 값(5), 스텝(*/15), 범위(1-5), 쉼표로 구분된 목록(1,15,30)을 지원합니다.

예시	의미
*/5 * * * *	5분마다
0 * * * *	매시 정각
7 * * * *	매시 7분
0 9 * * *	매일 로컬 시간 오전 9시
0 9 * * 1-5	평일 로컬 시간 오전 9시
30 14 15 3 *	3월 15일 로컬 시간 오후 2시 30분

요일은 일요일에 0 또는 7, 토요일에 6을 사용합니다. L, W, ?와 같은 확장 구문이나 MON, JAN 같은 이름 별칭은 지원되지 않습니다.

day-of-month와 day-of-week가 모두 제한된 경우, 어느 한 필드라도 일치하면 해당 날짜가 매칭됩니다. 이는 표준 vixie-cron 시맨틱을 따릅니다.

예약 작업 비활성화

환경에서 CLAUDE_CODE_DISABLE_CRON=1을 설정하면 스케줄러를 완전히 비활성화합니다. cron 도구와 /loop이 사용 불가능해지며, 이미 스케줄링된 작업도 실행이 중단됩니다. 비활성화 플래그의 전체 목록은 환경 변수를 참조하세요.

제한 사항

세션 범위 스케줄링에는 본질적인 제약이 있습니다:

• 작업은 Claude Code가 실행 중이고 유휴 상태일 때만 실행됩니다. 터미널을 닫거나 세션을 종료하면 모든 작업이 취소됩니다.
• 누락된 실행에 대한 보정이 없습니다. 장시간 실행되는 요청으로 Claude가 바쁜 동안 작업의 예정 시간이 지나면, Claude가 유휴 상태가 되었을 때 한 번만 실행되며, 누락된 간격마다 한 번씩 실행되지는 않습니다.
• 재시작 시 지속성이 없습니다. Claude Code를 재시작하면 모든 세션 범위 작업이 지워집니다.

무인으로 실행되어야 하는 cron 기반 자동화의 경우, schedule 트리거가 있는 GitHub Actions 워크플로를 사용하거나, 그래픽 설정 흐름을 원한다면 데스크톱 예약 작업을 사용하세요.