스냅샷

스냅샷 (Snapshots)

Shadow-git 스냅샷은 턴 경계에서 작업 공간을 캡처해서 에이전트가 무엇을 바꿨는지 검토하고, 실제 git 기록을 건드리지 않고 되돌릴 수 있게 해줘요.

출처: 문서

본문

개요 (Overview)

스냅샷이 활성화되면 Docker Agent는 에이전트가 실행되는 동안 작업 디렉터리의 상태를 기록해요. 각 체크포인트는 프로젝트 자신의 .git 과 완전히 분리된 Docker Agent 데이터 디렉터리 아래의 shadow git 저장소에 저장돼요. 이를 통해 다음을 할 수 있어요:

특정 턴에서 에이전트가 건드린 파일이 정확히 어떤 것인지 검토
/undo 로 가장 최근 변경 되돌리기
작업 공간을 이전 체크포인트로 — 또는 에이전트 전 상태까지 — 재설정

스냅샷은 디스크의 파일에만 닿아요. 저장소에 커밋을 쓰지 않고, HEAD를 움직이지 않으며, git log 나 git status 에 나타나지 않아요.

Note git 저장소 전용 (Git repositories only) 스냅샷 메커니즘은 git worktree 밖에서는 no-op이에요. 어떤 파일이 프로젝트에 속하는지 범위를 정하고 저장소의 무시 규칙을 미러링하려면 git 저장소가 필요해요.

스냅샷 활성화 (Enabling Snapshots)

가장 간단한 방법은 사용자 구성에서 모든 에이전트에 대해 전역으로 활성화하는 것이에요:

# ~/.config/cagent/config.yaml
settings:
  snapshot: true

snapshot 을 생략하거나 false 로 설정하면 자동 스냅샷이 꺼진 채로 둬요.

전역으로 활성화하는 대신 단일 에이전트에 snapshot 내장 훅을 연결할 수도 있어요:

hooks:
  turn_start:
    - type: builtin
      command: snapshot
  turn_end:
    - type: builtin
      command: snapshot
  session_end:
    - type: builtin
      command: snapshot

수동으로 구성된 스냅샷 훅은 settings.snapshot 이 설정되지 않았어도 항상 실행돼요. 완전한 구성은 examples/snapshot_hooks.yaml 참고.

TUI에서 스냅샷 사용 (Using Snapshots in the TUI)

스냅샷이 활성화되면 TUI는 두 개의 슬래시 명령을 노출해요:

/undo 는 가장 최근 스냅샷에서 파일을 복원해요(한 단계 뒤로).
/snapshots 는 캡처된 모든 스냅샷과 각각의 파일 수를 나열하는 대화상자를 열어요. ↑ / ↓(또는 j / k)로 항목을 강조하고 r 을 눌러 작업 공간을 그 시점으로 재설정해요. <original> 을 선택하면 모든 스냅샷을 되돌리고 작업 공간을 에이전트 전 상태로 가져와요. Esc 는 아무것도 바꾸지 않고 대화상자를 닫아요.

어느 명령도 세션 트랜스크립트에서 메시지를 제거하지 않아요 — 디스크의 파일에만 닿아요. 두 명령(및 명령 팔레트 항목)은 스냅샷이 꺼져 있으면 숨겨져요.

동작 원리 (How It Works)

Shadow 저장소. worktree에 대해 첫 스냅샷이 찍힐 때, Docker Agent는 데이터 디렉터리(기본 ~/.cagent/snapshot/...) 아래에 worktree 경로의 해시로 키가 매겨진 별도의 shadow git 디렉터리를 초기화해요. shadow 저장소는 tree 객체만 저장해요 — 커밋을 쓰지 않고 소스 저장소의 .git 에 절대 닿지 않아요.
무시 규칙이 미러링돼요. 각 캡처 전에 소스 저장소의 .gitignore 와 info/exclude 규칙이 shadow 저장소로 미러링되어 무시된 파일이 스냅샷에 절대 나타나지 않게 해요.
큰 파일이 건너뛰어져요. 새로 추가된 2 MiB보다 큰 파일은 shadow 저장소를 작게 유지하기 위해 스냅샷에서 제외돼요.
변경 시에만 체크포인트. 파일이 실제로 변경된 때만 체크포인트가 기록되므로, 최종 no-op 모델 응답이 마지막 의미 있는 스냅샷을 숨기지 않아요.
작업 디렉터리에 범위 지정. 스냅샷 작업은 worktree 안의 에이전트 작업 디렉터리에 범위가 지정되어, 하위 디렉터리 에이전트는 그 디렉터리 아래의 파일만 캡처하고 복원해요.
가비지 수집. session_end 에 스냅샷을 연결하면(또는 전역으로 활성화하면) shadow 저장소에 대해 git gc 를 실행해서 오래되고 참조되지 않은 객체가 시간이 지나며 정리돼요.

참고 (See Also)

Hooks — snapshot 내장과 그것이 실행될 수 있는 이벤트.
Terminal UI — /undo 및 /snapshots 명령.
examples/snapshot_hooks.yaml — 완전한 스냅샷 훅 구성.

스냅샷