체크포인트와 `/rollback` — 프로젝트의 안전망

AI 에이전트가 변경을 수행하는 걸 지켜보면서 “잠깐, 그건 의도한 게 아니었는데?“라고 생각해 본 적 있나요? 다들 겪어봤을 겁니다. 그래서 Hermes Agent에 이제 기본 제공되는 안전망이 포함되었습니다: 체크포인트. 비디오 게임의 세이브 포인트라고 생각하면 됩니다 — 위험한 작업을 수행하기 전에 프로젝트의 스냅샷을 찍어두고, 단 하나의 명령으로 복원할 수 있습니다.

체크포인트란 무엇인가?

체크포인트는 파괴적인 작업을 수행하기 전에 프로젝트의 자동 스냅샷을 찍는 기능입니다. 에이전트가 파일을 삭제하거나, 코드를 덮어쓰거나, 위험한 터미널 명령을 실행하려고 하면, 먼저 현재 상태를 저장합니다. 나중에 이 스냅샷들 중 원하는 시점으로 롤백할 수 있습니다.

가장 좋은 점은? 실제 프로젝트의 .git 히스토리는 절대 건드리지 않는다는 것입니다. Hermes는 ~/.hermes/checkpoints/store/에 있는 공유 섀도우 저장소를 사용합니다 — 별도의 git 저장소로, 모든 것을 체계적으로 정리하고 프로젝트 간 중복을 제거합니다.

시작하기: 체크포인트 활성화

체크포인트는 v2부터 옵트인(opt-in) 방식입니다. 대부분의 사용자에게 필요하지 않고, 저장 공간이 시간이 지남에 따라 커질 수 있으므로 기본값은 꺼져 있습니다.

단일 세션에서 활성화:

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

스팸 걱정은 마세요 — 에이전트는 턴마다 디렉토리당 최대 하나의 체크포인트만 생성하므로, 긴 세션도 깔끔하게 유지됩니다.

세션 내에서 `/rollback` 사용하기

체크포인트가 활성화되면, 채팅에서 강력한 슬래시 명령을 사용할 수 있습니다:

명령	기능
`/rollback`	변경 통계와 함께 모든 체크포인트 나열
`/rollback <N>`	체크포인트 N으로 복원, 직접 수정한 내용은 유지
`/rollback <N> --all`	전체 복원 — 직접 수정한 내용도 덮어씀
`/rollback diff <N>`	체크포인트 N과 현재 사이의 변경 사항 미리보기
`/rollback <N> <file>`	체크포인트 N에서 단일 파일 복원

체크포인트 목록을 확인하는 화면은 다음과 같습니다:

📸 /path/to/project에 대한 체크포인트:

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

  /rollback <N>             체크포인트 N으로 복원 (직접 수정 내용 유지)
  /rollback <N> --all       전체 복원, 직접 수정 내용도 덮어씀
  /rollback diff <N>        체크포인트 N 이후 변경 사항 미리보기
  /rollback <N> <file>      체크포인트 N에서 단일 파일 복원

셸에서 저장소 관리하기

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

hermes checkpoints              # 크기, 프로젝트 수, 세부 내역 표시
hermes checkpoints status       # 위와 동일
hermes checkpoints list         # status의 별칭
hermes checkpoints prune        # 강제 정리: 고아 데이터, 오래된 데이터, 크기 제한
hermes checkpoints clear        # 모든 것 삭제 (확인 후 진행)
hermes checkpoints clear-legacy # 이전 v1 마이그레이션 아카이브 제거

출력 예시:

체크포인트 기본 경로: /home/you/.hermes/checkpoints
총 크기:      142.3 MB
  store/         138.1 MB
  legacy-*       4.2 MB
프로젝트:        12

  WORKDIR                                                       COMMITS    LAST TOUCH  STATE
  /home/you/code/hermes-agent                                        20       2h 전  live
  /home/you/code/experiments/rl-runner                                8       1d 전  live
  /home/you/code/old-prototype                                        3       9d 전  orphan

설정 옵션

~/.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

모든 것을 비활성화하고 싶나요?

checkpoints:
  enabled: false
  auto_prune: false

내부 동작 방식

Hermes가 파일을 수정하려는 도구를 감지하면 다음 단계를 수행합니다:

해당 파일의 프로젝트 루트를 확인
공유 섀도우 저장소를 초기화하거나 재사용
변경 사항을 스테이징하고, 트리를 구성한 다음, 프로젝트별 ref(refs/hermes/<project-hash>)에 커밋

이러한 ref들이 체크포인트 히스토리를 형성하며, /rollback을 통해 확인하고 복원할 수 있습니다.

마무리

체크포인트는 에이전트가 코드를 작업하게 할 때 마음의 평화를 줍니다. 실험 중이든, 리팩토링 중이든, 아니면 그냥 안전망이 필요하든, /rollback이 여러분을 지켜줍니다. 활성화해 두고 잊어버리세요. 언제든 되돌릴 수 있다는 사실에 안심하고 말이죠.

즐거운 코딩 되세요 — 그리고 기억하세요, 세이브 포인트가 존재하는 데는 이유가 있습니다!