체크포인트와 `/rollback` — 파괴적인 작업을 위한 안전망

체크포인트와 /rollback — 파괴적인 작업을 위한 안전망

AI 에이전트가 rm -rf 같은 명령어를 실행하거나 파일을 덮어쓰는 걸 보면서 “정말 뭘 하는지 알고 있는 걸까?“라고 생각해본 적 있나요? Hermes Agent v2에서는 이제 제대로 된 안전망 — 체크포인트 — 을 제공합니다. 위험한 작업 전에 프로젝트 스냅샷을 찍어두고, 단 하나의 명령어로 복원할 수 있죠.

가장 좋은 점은? 완전히 옵트인(opt-in) 방식이라는 겁니다. 대부분의 사용자는 /rollback을 건드릴 일이 없고, shadow-store 저장 공간이 시간이 지나면서 커질 수 있기 때문에 기본값은 꺼져 있습니다. 하지만 필요할 때는 생명의 은인이 되어줍니다.

체크포인트 활성화하기

세션별로 간단한 플래그로 체크포인트를 활성화할 수 있습니다:

hermes chat --checkpoints

또는 ~/.hermes/config.yaml에서 전역으로 활성화할 수도 있습니다:

checkpoints:
  enabled: true

끝입니다. 활성화하면 Hermes가 파괴적인 작업이 발생하기 전에 자동으로 프로젝트 스냅샷을 찍습니다.

체크포인트가 생성되는 조건

Hermes는 다음 상황 전에 자동으로 체크포인트를 생성합니다:

• 파일 도구 — write_file 및 patch
• 파괴적인 터미널 명령어 — rm, rmdir, cp, install, mv, sed -i, truncate, dd, shred, 출력 리다이렉트(>), 그리고 git reset/clean/checkout

에이전트는 턴마다 디렉토리당 최대 1개의 체크포인트를 생성하므로, 오래 실행되는 세션에서도 스냅샷이 남발되어 저장 공간을 낭비하지 않습니다.

내부 동작 방식

이 모든 마법은 내부 체크포인트 매니저(Checkpoint Manager) 를 통해 이루어집니다. 이 매니저는 ~/.hermes/checkpoints/store/에 단일 공유 shadow git 저장소를 유지합니다. 실제 프로젝트의 .git은 절대 건드리지 않으며, 모든 것은 이 별도의 저장소에 보관됩니다.

동작 흐름은 다음과 같습니다:

1. Hermes가 작업 트리의 파일을 수정하려는 도구를 감지합니다.
2. 대화 턴당(디렉토리별) 합리적인 프로젝트 루트를 결정합니다.
3. 공유 shadow 저장소를 초기화하거나 재사용합니다.
4. 프로젝트별 인덱스에 파일을 스테이징하고, 트리를 구성한 다음 프로젝트별 ref(refs/hermes/<project-hash>)에 커밋합니다.

모든 프로젝트가 동일한 저장소를 공유하므로, git의 콘텐츠 주소 지정 객체 데이터베이스가 프로젝트 간 및 턴 간 중복을 제거합니다 — 즉, 동일한 콘텐츠에 대해 저장 공간을 낭비하지 않습니다.

세션에서 /rollback 사용하기

체크포인트가 활성화된 세션에 있다면, 다음과 같은 슬래시 명령어를 사용할 수 있습니다:

명령어	설명
/rollback	변경 통계와 함께 모든 체크포인트 나열
/rollback <N>	체크포인트 N으로 복원, 직접 수정한 내용은 유지 (마지막 채팅 턴도 실행 취소)
/rollback <N> --all	전체 복원 — 직접 수정한 내용도 덮어씀
/rollback diff <N>	체크포인트 N과 현재 상태 간의 차이점 미리보기
/rollback <N> <file>	체크포인트 N에서 단일 파일 복원

/rollback을 실행하면 다음과 같은 형식의 목록이 표시됩니다:

📸 Checkpoints for /path/to/project:

  1. 4270a8c  2026-03-16 04:36  before patch  (1 file, +1/-0)
  2. eaf4c1f  2026-03-16 04:35  before write_file
  3. b3f9d2e  2026-03-16 04:34  before terminal: sed -i s/old/new/ config.py  (1 file, +1/-1)

셸에서 저장소 관리하기

세션 밖에서는 CLI 명령어로 체크포인트 저장소를 확인하고 관리할 수 있습니다:

명령어	설명
hermes checkpoints	전체 크기, 프로젝트 수, 프로젝트별 세부 정보 표시
hermes checkpoints status	기본 checkpoints 명령어와 동일
hermes checkpoints list	status의 별칭
hermes checkpoints prune	강제 정리: 고아/오래된 항목 삭제, GC, 크기 제한 적용
hermes checkpoints clear	전체 체크포인트 베이스 삭제 (확인 메시지 표시)
hermes checkpoints clear-legacy	v1 마이그레이션의 legacy-* 아카이브만 삭제

설정 옵션

~/.hermes/config.yaml에서 체크포인트 동작을 세밀하게 조정할 수 있습니다:

checkpoints:
  enabled: false              # 마스터 스위치 (기본값: false — 옵트인)
  max_snapshots: 20           # 프로젝트당 최대 체크포인트 수
  max_total_size_mb: 500      # 전체 저장소 크기 하드 리밋
  max_file_size_mb: 10        # 이 크기보다 큰 단일 파일은 건너뜀
  auto_prune: true            # 시작 시 정리 실행 (기본값: 켜짐)
  retention_days: 7           # 이 기간보다 오래된 항목 삭제
  min_interval_hours: 24      # 자동 정리 사이 최소 시간 간격

중요한 참고 사항: 자동 정리(auto-prune)는 “고아(orphan)” 항목(작업 디렉토리를 찾을 수 없는 경우)을 절대 삭제하지 않습니다. 시작 시 작업 디렉토리가 없다는 것은 프로젝트가 삭제되었거나, 아직 마운트되지 않은 외장 볼륨이나 네트워크 공유일 수 있기 때문입니다. 고아 항목 정리는 확인 메시지를 먼저 표시하는 명시적인 hermes checkpoints prune 명령어로만 수행됩니다.

모든 기능을 비활성화하려면:

checkpoints:
  enabled: false
  auto_prune: false

enabled: false인 경우 체크포인트 매니저는 아무 작업도 하지 않으며 git 작업을 시도하지 않습니다. auto_prune: false인 경우 수동으로 hermes checkpoints prune을 실행할 때까지 저장소는 계속 커집니다.

마무리

체크포인트를 사용하면 Hermes가 자유롭게 작업하도록 맡겨도 언제든지 알려진 정상 상태로 롤백할 수 있다는 확신을 얻을 수 있습니다. 리팩토링을 실험하거나, 위험한 명령어를 테스트하거나, 그냥 마음의 평화를 원할 때 /rollback 명령어가 여러분을 지켜줍니다.

다음 세션에서 한번 사용해 보세요 — 작업 흐름의 필수 요소가 될 수도 있습니다.