Gemini-cli: session 저장 및 되돌리기

Gemini CLI에서 Session이란?

In Gemini CLI, a session is one instance of a running gemini process.

gemini 프로세스가 실행된 하나의 인스턴스 단위로,

• gemini를 실행한 순간부터
• /quit 또는 <Ctrl-C>로 종료할 때까지의 상호작용(주로 conversation)의 흐름이 session임
• 단 /clear 명령어는 프로세스를 종료하진 않으나, model context를 초기화하고, 이후 요청에 새로운 session을 생성하여 할당하게 됨: 즉, 하나의 gemini 프로세스 실행 중 여러 session이 생길 수 있음.

이 글은 session을 관리하는 다음 command를 실제로 익히는 것임.

• /resume save
• /resume list
• /resume resume
• /resume delete
• /resume share
• /resume
• /rewind
• /restore

참고로 /chat은 /resume의 alias 임.

 

미리 결론을 말하자면

 

/resume 은 session의 conversaton의 복원에 사용되고,

/rewind 와 /restore 는 workspace의 파일들의 복원도 가능 (/rewind는 선택 가능).

 

/resume과 /restore는 cross-session이나, /rewind는 within-session(or in-session)임.

• cross-session"이란 프로세스 재시작 전후를 넘나들 수 있음(특정 파일을 사용하여 저장됨)
• "within-session"은 현재 실행 중인 프로세스 내부에서만 유효하다는 의미(휘발성으로 파일로 저장되지 않음)

2026.03.26 현재
restore 명령어는 좀 동작이 불안정하다.
파일이 복원되지 않는 경우도 몇차례 겪은터라....

 

---

1. 실습용 프로젝트 만들기

먼저 Hugging Face 실습용 conda 프로젝트를 하나 만듦.

# 1. 환경 생성
conda create -n hf-gemini-demo python=3.10 -y
conda activate hf-gemini-demo

# 2. PyTorch 2.7.0 설치 (CUDA 버전에 맞게 선택)
# nvidia-smi 로 확인.

# CUDA 12.8 (최신 권장)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128

# CUDA 12.6
# pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126

# CUDA 11.8
# pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

# CPU only
# pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

# 3. HuggingFace 스택
pip install transformers datasets huggingface_hub accelerate

mkdir -p hf-gemini-demo/src

 

다음의 예제용 python code 파일 하나 만듦 (서브디렉토리 src를 먼저 만들어야 함).

# src/check_env.py
from transformers import pipeline
from datasets import load_dataset

print("Transformers import: OK")
print("Datasets import: OK")

 

현재 디렉토리 구조는 대략 다음과 같음:

hf-gemini-demo/
└── src
     └── check_env.py

2024.09.12 - [개발환경] - [Conda] miniconda 설치하기: Windows, macOS, WSL

[Conda] miniconda 설치하기: Windows, macOS, WSL

---

2. .gemini/settings.json 만들기

주의할 점은, /restore 는 checkpointing 기능이 켜져 있어야만 사용 가능함.

• Gemini-CLI가 파일을 수정하는 tool인 write_file, replace 등을 실행할 때마다 checkpoint가 자동으로 생성됨.
• 각 checkpoint에는 file의 snapshot(=shadow Git repo), 대화기록, 실행된 tool의 호출(call)정보가 함께 저장됨.
• 각 checkkpoint 파일의 이름은 "timestamp-수정된_파일명-tool이름" 으로 구성됨.

 

설정 관련 참고사항:

• sessionRetention 설정을 통해 session 정리 정책을 명확히 할 수 있음
• maxCount는 유지할 최대 세션 개수임: 이 개수를 넘으면 오래된 세션부터 자동 삭제됨
• maxAge는 삭제 기준 기간을 설정.
• minRetention은 최소 보존 기간을 설정.
• maxSessionTurns는 한 세션에서 유지할 최대 turn 수임.

프로젝트 루트에서 아래를 실행함.

mkdir -p .gemini

 

이후 다음과 같이 .gemini/settings.json 편집.

{
  "general": {
    "checkpointing": {
      "enabled": true
    },
    "sessionRetention": {
      "enabled": true,
      "maxAge": "30d",
      "maxCount": 50,
      "minRetention": "1d"
    }
  },
  "model": {
    "maxSessionTurns": 100
  }
}

• general.checkpointing.enabled : /restore용 checkpointing 활성화 (기본은 비활성화임)
• general.sessionRetention.enabled : 세션 자동 정리 기능 on/off (기본은 활성화)
• general.sessionRetention.maxAge : 이 기간보다 오래된 세션 자동 삭제 기준 (30d 가 기본)
• general.sessionRetention.maxCount : 유지할 최대 세션 개수 (기본은 undefined)
• general.sessionRetention.minRetention : 이 기간보다 새로운 세션은 자동 삭제하지 않음 (기본은 1d)
• model.maxSessionTurns : 한 세션에서 허용할 최대 turn 수 (기본은 -1로 제한 없음)

참고로 Gemini-CLI의 설정 파일 은

• 전역: ~/.gemini/settings.json,
• 프로젝트 전용: .gemini/settings.json.

프로젝트 설정이 전역 설정보다 우선함.

---

3. Gemini CLI 실행하기

이제 반드시 프로젝트 루트에서 Gemini CLI를 실행함.

gemini

 

기억할 것은 manual conversation checkpoint (resume이 사용하며, 사용자에 의한 명시적 저장 필요)는 project-scoped임.

• 현재 디렉터리 기준으로 저장
• 설정 변경시 같은 프로젝트 디렉토리에서 gemini를 실행하여 다시 불러와야 적용됨.

/resume save, /resume list, /resume resume 의
저장 대상이 현재 프로젝트 기준임을 기억할 것.
이들은 coversation checkpoint 를 관리.

---

4. 첫 대화 만들기

Gemini CLI 안에서 아래를 입력함.

이 프로젝트는 Hugging Face를 사용하는 conda 개발환경 실습용 프로젝트야.
현재 파일 구조를 확인하고, src/check_env.py가 어떤 역할인지 설명해줘.

 

---

5. 현재 상태를 manual conversation checkpoint로 저장하기

이제 현재 상태(conversation session)를 baseline이라는 이름의 conversation checkpoin로 저장함.

/resume save baseline

• 지금까지의 대화 상태를 baseline이라는 tag로 저장하는 것임.
• 이와 같이 manual conversation checkpoint를 만들어 분기점으로 사용가능.
• Gemini CLI를 재시작 시킨 경우 이 저장된 과거의 converation chechpoint를 통해 과거의 session을 이어나갈 수 있음.

/resume 을 통한 conversation checkpoint는
프로젝트 디렉토리 내의 file 들의 변경 등에 대한 복원이나 변경은 저장되지 않음:
오직 conversation만 저장.

---

6. 저장된 checkpoint 목록 보기

다음으로 저장이 됐는지 확인함.

/resume list

• baseline이 보이면 정상임.

list는 현재 프로젝트 안에서 수동(manual) 저장한 conversation checkpoint tag를 보여 줌.

---

7. 대화를 더 진행한 뒤 두 번째 manual conversation checkpoint 저장하기

다음의 대화를 더 진행함.

src/check_env.py를 좀 더 실용적으로 만들고 싶어.
Hugging Face pipeline을 실제로 만드는 예제를 추가하는 방향으로 수정안을 먼저 제안해줘.
아직 file은 직접 수정하지 마.

 

이후 응답이 나오면 다음의 명령어로 두 번째 conversation checkpoint 저장 지점을 생성.

/resume save after-pipeline-plan

 

제대로 저장이 되었는지 다음으로 확인.

/resume list

• 이제 baseline과 after-pipeline-plan 두 개가 보임.

중간중간 분기점을 이름(tag명) 붙여 저장할 수 있음.

---

8. 저장한 이전 conversation checkpoint 지점으로 다시 돌아가기

첫 번째 저장 지점으로 다시 돌아가려면 다음을 실행.

/resume resume baseline

• 이 명령은 baseline 저장 시점의 대화 상태로 돌아가게 함.
• 이 기능은 "같은 지점에서 다른 방향으로 대화를 다시 펼치고 싶을 때" 쓰는 것임.

 

복귀 후 이렇게 입력해 봄.

지금은 pipeline 예제보다,
이 conda 환경을 점검하기 위한 체크리스트만 먼저 정리해줘.

 

이렇게 하면 baseline에서 새로운 conversation branch로 작업을 진행할 수 있음: 특정 의사 결정 시점을 보존하는 용도.

주의할 점은 workspace 내의 파일들은 저장되지 않는다는 점임.

 

---

9. 필요 없는 checkpoint 삭제하기

after-pipeline-plan이 필요 없다고 가정하고 삭제를 하려면 다음을 실행.

/resume delete after-pipeline-plan

 

다음으로 삭제된 것을 확인가능.

/resume list

• after-pipeline-plan이 목록에서 사라져 있어야 정상임.
• delete <tag>는 수동 저장한 checkpoint를 지우는 subcommand임.

---

10. 현재 conversation을 파일로 내보내기

이제 현재 대화를 파일로 저장하는 방법은 다음과 같은 2가지 방식이 있음.

10-1. Markdown 형식으로 저장:

/resume share hf-session.md

---

10-2. JSON 형식으로 저장:

/resume share hf-session.json

• share [filename]는 현재 conversation을 Markdown 또는 JSON으로 기록함.
• 파일명을 안 주면 CLI가 자동으로 생성할 수도 있음.

---

다음으로 파일 생성 여부를 확인 가능.

!ls

---

11. auto 저장 세션 browser 열기

/resume 단독 사용시 auto-saved session browser를 보여줌.

위의 이미지에서 상단은 auto 이고, 하단은 앞서 설명한 manual conversation checkpoins 관련 subcommand를 보여줌.

• 이는 auto-saved session browser를 여는 동작임.

다음은 auto-saved session browser 의 캡처임:

• 이는 과거 자동 저장된 세션들을 보여줌.
• 여기서 위아래 화살표로 특정 session을 선택하여 다시 열 수 있음: Enter
• 필요하면 삭제도 가능함: x

---

참고: auto-saved session (gemini --resume)

auto-saved session과 관련하여 /resume은 cross-session 임.

• 이후 Gemini CLI가 다시 시작할 때, --resume 옵션을 주면 가장 최근 session 을 이어서 할 수 있음.
• --resume 에 option argument로 복원한 session을 지정할 수 있음.
• 어떤 option argument 에 어떤 session이 대응하는지는 gemini --list-sessions 를 통해 확인 가능함.

auto-saved session에는

• 모델과 주고받는 모든 대화가 백그라운드에서 자동으로 저장됨.
• 저장 내용에는 프롬프트·응답, 툴 실행 기록(입출력), 토큰 사용량, 모델의 추론 요약이 포함.
• 저장위치는 ~/.gemini/tmp/<project_hash>/chats/ 이며, 타임스탬프가 붙은 .json 파일로 관리
• 별도의 저장 명령 없이도 모델에 요청을 보내는 순간 자동 생성.
• 각 session마다 index가 할당되어 있음.

session은 하나의 Gemini CLI 실행 인스턴스라고 볼 수 있음. 다음 예를 참고할 것:

# 예시 시나리오
gemini 실행              → session-2026-03-26T09-00-00.json 생성 (index 3)
  → 질문1 전송            → 위 파일에 turn 1 추가
  → 질문2 전송            → 위 파일에 turn 2 추가
  → /clear               → 아직 파일 분리 안 됨
  → 질문3 전송            → session-2026-03-26T09-30-00.json 생성 (index 2)
gemini 종료

gemini 재실행           → session-2026-03-26T10-00-00.json 생성 (index 1)

 

/resume browser 는 세션 관리의 핵심 UI 임.

 

여기서 구분해야 할 점은 다음임.

• /resume save, /resume list, /resume resume은 manual conversaion checkpoint 관리
• /resume 단독은 auto-saved session에 대한 session browser 를 연다.

같은 계열이지만 다루는 대상이 다름.

/resume의 auto-saved session은
뒤에 다루는 /restore 용 checkpointing과는 조금 다른 기능임.

/restore의 checkpointing은
file system을 수정하는 tool을 승인할 때 별도 checkpoint를 남기는 기능이며
기본 비활성화 상태라 settings.json에서 켜야 함.

반면
auto-saved session은
대화 history 자체를 저장하는 기본 세션 관리 기능임.

---

12. /rewind 와 /restore 를 위한 실제 변경 이력 만들기

/rewind와 /restore는

• 되감을 대상이 있어야
• 의미가 있음.

이들은 단순히 conversation 만이 아닌
file들의 변경사항도 복원가능함.

 

/rewind의 경우엔 Gemini-CLI가 자신의 tool로 수정한 file의 변경사항만 복구 가능함(사용자가 직접 편집한 건 복구 못함)

 

/restore는 /resume과 같이 cross-session으로 동작하나,

/rewind는 in-session으로 동작함 (특정 위치에 파일로 복원을 위한 저장을 하지 않음).

---

그러므로 Gemini 에게 실제 파일 수정을 지시.

src/check_env.py를 직접 수정해줘.
sentiment-analysis pipeline을 만들고,
예시 문장 하나를 추론해서 결과를 출력하게 해줘.

 

수정 이 끝나면 확인함.

 

!cat src/check_env.py

---

참고: /rewind

 

/rewind를 쓰기 위해선 충분한 interaction과 file change 가 있어야 함.

• 현재 session의 메모리에서 AI의 편집 내역을 추적하여 파일의 복구가 가능.
• 현재 session 내에서만 동작 가능(in-session 방식)
• 별도의 저장 위치가 없음.

/rewind는 과거 interaction을 되감는 기능이며, destructive action으로 실행 후 취소가 불가함(주의!).

 

/rewind로 특정 시점으로 돌리고 나며
돌리기 전의 상태로의 복구는 할 수 없게 되므로
(destructive action)
사용시 주의 해야함.

---

13. /rewind 사용하기

다음을 실행.

/rewind

• Esc를 두 번 눌러도 같은 동작임.
• /rewind는 과거 interaction 목록을 보여 주고, 되감고 싶은 지점을 선택할 수 있음.
• 그 뒤 "conversation만 되감기", "code changes만 되돌리기", "둘 다 되감기" 등을 선택 가능함
  "code changes만 되돌리기" 는 chat history는 유지하고 파일만 복원시킴.

 

 

다시 강조하지만, /rewind는 within-session이고 destructive action임.

---

14. /restore 사용하기

앞에서 checkpointing.enabled를 켜 두었고,

실제 file edit도 한 번 일어났으므로 /restore를 시도할 수 있음.

 

주의할 것은

• checkpointing은 기본 비활성화이며,
• file system을 수정하는 tool을 승인할 때 checkpoint가 자동 생성된다는 점임.

먼저 복원 가능한 checkpoint 목록을 봄.

/restore

 

/restore를 위한 checkpoint는 ~/.gemini/history/<project_hash>/ 에 저장됨.

단순 파일이 아닌 shadow Git repository(저장소) 임..

그다음 목록에 나온 checkpoint 파일명을 사용해 복원함.

/restore <checkpoint_file>

 

/restore는

• 프로젝트 파일,
• conversation history,
• 원래 tool call 제안까지 checkpoint 시점으로 되돌림.

 

즉 /rewind와 비슷해 보여도, /restore는 명시적 checkpoint 파일을 대상으로 동작하는 복원 기능임.

 

이와 달리 /rewind는 현재 session history 에 기반한 복원임.

/restore 보다는 /rewind를 사용하는게 나아보임.

---

15. /chat은 alias라고만 기억하면 됨

지금까지 전부 /resume으로 진행했지만,

같은 기능을 /chat으로 써도 됨.

 

예를 들면 아래 둘은 같은 기능임.

/resume save baseline
/chat save baseline

/resume list
/chat list

• /chat은 /resume의 alias
• 같은 session browser와 checkpoint subcommand를 제공

---

16. 마무리

수동 checkpoint 관련

• /resume save, /resume list, /resume resume, /resume delete, /resume share는
• manual conversation checkpoint 관리용임

자동 저장 관련

• /resume 단독은 auto-saved session browser임
• --resume 옵션으로 gemini cli를 재시작할 때 이어서 할 session을 지정가능함.

/rewind 와 /restore

• /rewind는 현재 세션 interaction을 기준으로 되감는 in-session 기능임
• /restore는 settings.json에서 checkpointing을 먼저 켜야 사용가능한 cross-session 복원 기능임

설정 관련.

• sessionRetention.maxCount는 유지할 최대 세션 개수임. 초과분은 오래된 세션부터 정리됨
• maxAge는 기간 기준, minRetention은 최소 보존 안전장치, maxSessionTurns는 세션 길이 제한임 

---

같이 보면 좋은 자료들

https://geminicli.com/docs/reference/commands/

CLI commands

 

https://geminicli.com/docs/cli/checkpointing/

Checkpointing

 

https://geminicli.com/docs/cli/rewind/

Rewind

 

https://geminicli.com/docs/cli/tutorials/session-management/

Manage sessions and history

 

https://geminicli.com/docs/cli/settings/

Gemini CLI settings (`/settings` command)

 

https://ds31x.tistory.com/574#1.-gemini-cli-%EC%84%A4%EC%A0%95-settings.json

Gemini CLI와 함께하는 터미널(CLI) 명령어 학습하기