Antigravity 전환 — 무료 사용자 요금제 가이드 전환

2026년 6월 18일부터 Gemini CLI는 무료·Pro·Ultra 사용자에게 서비스를 중단합니다. 무료로 쓰던 분들이 가장 궁금한 "전환 후에도 무료로 쓸 수 있나? 한도는 그대로인가? 무엇을 미리 준비해야 하나?"를 정리합니다.

📣 공식 소개 블로그 — "Introducing Google Antigravity CLI"

1. Antigravity CLI란?

Antigravity CLI는 Google Antigravity 2.0의 "터미널 UI 대안"입니다. 데스크톱 앱(2.0)과 동일한 "agent harness"(에이전트 실행 환경)를 공유하며, 동일한 설정을 쓰고, CLI에서 시작한 대화를 데스크톱 앱으로 가져올 수 있습니다.

• 핵심 가치: 에이전트의 호출(invoke) · 모니터링(monitor) · 상호작용(interact) 세 가지에 집중
• GUI를 흉내내지 않습니다 — 그건 Antigravity 2.0의 영역. CLI는 "진정으로 빠르고 가벼운 터미널 경험"에만 집중

2. Antigravity CLI ↔ Antigravity 2.0 관계

3. Gemini CLI와의 관계

블로그는 두 도구의 관계를 다음과 같이 명시합니다:

• Antigravity CLI는 Gemini CLI의 핵심 제품·하니스 컴포넌트에서 영감을 받음
• Gemini 모델과 함께 최적화된 "공유 에이전트 하니스" 단일화가 큰 그림
• 이런 통일을 통해 개발자 경험을 한 곳에 집중 → 향후 개선 속도 ↑

4. 기존 Gemini CLI 사용자의 시작 방법

1. 다운로드 페이지의 안내에 따라 Antigravity CLI 설치 → antigravity.google/download
2. 마이그레이션 가이드를 따라 기존 자산(스킬 · MCP 서버 · 기타 커스터마이징)을 옮김 → antigravity.google/docs/gcli-migration
3. 슬래시 명령 · 설정 · 키바인딩 전체 레퍼런스는 Antigravity CLI 공식 문서에서 확인

5. 향후 로드맵 (Looking Forward)

• Antigravity CLI는 핵심 하니스와 에이전트 패러다임의 모든 개선을 계속 상속·통합
• Antigravity 2.0 = 기능 종합성(comprehensiveness) 최적화
• Antigravity CLI = 속도·낮은 오버헤드(speed and low overhead) 최적화
• 두 제품 모두 Antigravity 제공물의 핵심 축으로 유지·확장

📋 5분 요약 — 가장 중요한 5가지

🔗 블로그가 안내하는 공식 자료

• 다운로드: antigravity.google/download
• Gemini CLI → Antigravity CLI 마이그레이션 가이드: antigravity.google/docs/gcli-migration
• 슬래시 명령·설정·키바인딩 전체 문서: Antigravity CLI 공식 docs (블로그에서 링크)
• 전환 발표문 (Developers Blog): developers.googleblog.com — Important update

출처: The Antigravity Team — "Google Antigravity CLI" (2026-05-20), antigravity.google/blog/introducing-google-antigravity-cli

1. 지금 내가 어떤 요금제로 쓰고 있는지부터 확인

본인의 현재 상태에 따라 영향 범위와 필요한 조치가 다릅니다. 아래 표에서 해당 행을 찾으세요.

자신이 어디 해당하는지 모르겠으면 터미널에서 /auth를 입력해 현재 인증 방법을 확인하세요. "Google account"라고 나오면 첫 행, "Gemini API key"라고 나오면 두 번째 행입니다.

2. ✅ 공식 발표문에서 확정된 변경 사항

Google Developers Blog가 명시한 내용만 추렸습니다:

3. ❓ 아직 공식적으로 확인 안 된 항목

마이그레이션 전 직접 확인 권장:

• Antigravity CLI 무료 등급 일일 한도 — 기존 1,000건/일이 유지되는지, 줄어드는지, 늘어나는지 미공개
• 인증 방법 호환성 — 기존 OAuth 토큰을 그대로 쓸 수 있는지, 새로 로그인해야 하는지 미공개
• 사용 가능 모델 목록 — 무료 등급에서 Gemini 3 Pro/Flash 어디까지 호출 가능한지 미공개
• 분당/시간당 요청 수(RPM) — 일일 한도와 별개의 burst 제한이 있는지 미공개
• GEMINI.md, .gemini/settings.json 호환성 — 새 CLI가 기존 설정 파일을 그대로 읽는지, 변환이 필요한지 미공개
• MCP 서버 호환성 — 등록된 MCP 서버가 그대로 작동하는지, "플러그인" 포맷으로 재패키징해야 하는지 미공개
• 유예 기간 연장 가능성 — 6/18 마감을 미루는 옵션이 있는지 미공개

4. 시나리오별 무료 사용자 액션 플랜

시나리오 A: "취미·학습용으로 가끔 쓴다"

권장: Antigravity CLI 무료 등급으로 이전 시도 → 한도·기능 확인 후 만족하면 계속, 부족하면 시나리오 B 또는 C로

• 📥 antigravity.google/download에서 다운로드
• 🔐 본인의 기존 Google 계정으로 로그인 (현재 OAuth 그대로 호환되리라 예상되나 확정 아님)
• 📂 기존 ~/.gemini/ 디렉토리는 지우지 말고 백업 — 명령 매핑이나 설정 호환에 참고용
• ⏱️ 첫 며칠 동안 일일 한도에 부딪히는지 모니터링 (/stats model로 사용량 확인)

시나리오 B: "매일 본격적으로 쓰는데 비용은 최소화하고 싶다"

권장: 유료 Gemini API 키로 전환 → Gemini CLI도 6/18 이후 계속 사용 가능

• Google AI Studio에서 API 키 발급 + 결제 등록
• export GEMINI_API_KEY=...로 인증 전환 (기존 OAuth 로그인 대체)
• 유료 키는 종량제 — 가벼운 사용은 월 1~2달러 수준 가능
• ✅ 발표문에 명시: "paid Gemini API keys via Gemini CLI remain accessible"
• 📌 단, Gemini CLI 자체 개발이 중단될 가능성이 높으므로 장기적으로는 Antigravity 이전 권장

시나리오 C: "팀 단위로 쓰고 안정성이 중요하다"

권장: Code Assist Standard 또는 Vertex AI(Gemini Enterprise Agent Platform)로 업그레이드

• 두 옵션 모두 공식 발표문에 "access remains unchanged"로 보장됨
• Gemini CLI도 계속 사용 가능 · Antigravity CLI로 자유 전환 가능
• 견적은 Google Cloud 영업 또는 Workspace 관리자 경로

시나리오 D: "Antigravity가 마음에 안 들면 어떡하지?"

대안: Gemini API 키만 발급해두고 다른 오픈소스 CLI 또는 IDE 확장으로 우회

• 오픈소스 CLI: Aider, Continue.dev, Cursor CLI 등이 Gemini API 키를 지원
• self-host MCP 서버: 일부 도구는 직접 운영 가능
• 다른 모델 병행: Claude(Anthropic), Codex(OpenAI), 또는 로컬 모델(Ollama/LM Studio) 결합

5. 전환 전 체크리스트

6월 18일이 되기 전 다음을 미리 점검하세요:

6. 비용 비교 (현행 기준선)

Antigravity 요금이 발표되면 이 표에 추가될 예정입니다. 지금은 의사결정 참고용으로 현재 Gemini CLI 요금만 정리합니다:

정확한 최신 가격은 Gemini CLI 공식 요금 페이지와 Google AI 가격 페이지를 확인하세요.

💬 프롬프트로 자동 점검

전환 준비를 Gemini CLI에게 직접 시킬 수도 있습니다:

> Gemini CLI에서 Antigravity CLI로의 전환을 준비해줘:
> 1. ~/.gemini 디렉토리를 ~/.gemini.backup-YYYYMMDD 로 복사 백업
> 2. /mcp list 결과를 .gemini/migration/mcp-servers.txt 로 저장
> 3. .gemini/agents/, .gemini/skills/, .gemini/commands/ 의
>    파일 목록을 .gemini/migration/custom-assets.md 로 정리
> 4. /auth 와 /stats model 결과를 .gemini/migration/account.txt 로 저장
> 5. 위 내용을 한 줄 요약으로 보여주고 다음 단계 4가지를 제안해줘
>    (Antigravity 다운로드 / 백업 위치 / MCP 재등록 / 한도 모니터링)

Antigravity CLI 개요

Antigravity 공식 문서 cli-overview 페이지를 한국어로 정리. 이 CLI가 무엇이고 Antigravity 2.0과는 어떤 관계인지, 그리고 어디서부터 학습을 시작해야 하는지 안내합니다.

Antigravity CLI란 무엇인가

Antigravity CLI는 Antigravity를 터미널에서 가볍게 사용할 수 있도록 만든 TUI(터미널 사용자 인터페이스) 환경입니다. Antigravity 2.0이 제공하는 핵심 에이전트 능력 — 다단계 추론, 다중 파일 편집, 도구 호출, 대화 히스토리 관리 — 을 그대로 가져와 터미널 안에서 그대로 사용할 수 있게 해줍니다.

철학적 차이 — CLI vs. Antigravity 2.0

Antigravity CLI는 Antigravity 2.0을 ‘대체’하는 것이 아니라, 터미널 우선(terminal-first)의 보완재로 자리 잡습니다. 두 도구는 같은 두뇌를 공유하면서도 최적화 지향점이 다릅니다.

두 도구를 잇는 통합 기능

두 도구는 서로 다른 사용자 인터페이스를 갖고 있지만, 내부 아키텍처와 사용자 자산 측면에서 다음 세 가지를 공유합니다.

시작하기와 마이그레이션

처음 설치

설치 절차는 본 가이드의 설치 가이드 또는 개발 환경 설정 섹션을 따라 진행합니다.

Gemini CLI에서 마이그레이션

이미 Gemini CLI를 사용해온 경우, 첫 실행 시 안내되는 일회성 마이그레이션 단계가 기존의 다음 항목들을 자동으로 가져옵니다.

• 익스텐션 (Extensions)
• 에이전트 스킬 (Skills)
• 사용자 설정 (Settings)

마이그레이션 절차의 단계별 안내는 본 가이드의 Antigravity 전환 가이드 섹션을 참고하세요.

심화 학습 — 어디서부터 읽을까

공식 문서가 권장하는 다음 단계와 그에 대응하는 본 가이드의 한국어 섹션을 함께 정리했습니다.

한눈 보기 요약

Antigravity CLI 사용 가이드

Antigravity 공식 문서 cli-using 페이지를 한국어로 정리. 설정 · 빠른 팁 · 키바인딩 3개 축으로 구성됩니다.

1. 설정 시스템

Antigravity CLI는 워크스페이스 동작, 보안 정책, 에디터 선호도, 시각 스타일, 성능을 모두 다루는 유연한 설정 시스템을 제공합니다. 설정에 접근하는 경로는 두 가지이며 어느 쪽으로 바꿔도 결과는 동일하게 같은 디스크 파일에 저장됩니다.

저장 위치 — JSON 파일

• 모든 설정은 평문 JSON 파일 ~/.gemini/antigravity-cli/settings.json 에 저장됩니다.
• 에디터로 직접 열어 편집해도 무방하며, MCP·스킬·훅 같은 복합 구조를 다룰 때는 직접 편집이 효율적입니다.

인터랙티브 설정 패널 — /config · /settings

실행 중인 프롬프트에서 /config 또는 /settings 를 입력하면 모든 옵션을 나열한 풀스크린 오버레이 메뉴가 열립니다.

• 항목을 선택하면 선택지 목록 또는 텍스트 입력 필드가 함께 표시됩니다.
• 값을 고르는 즉시 디스크에 반영되고 메인 목록으로 돌아옵니다.
• 각 항목의 의미·기본값·시나리오별 추천 조합은 본 가이드의 /config 메뉴 섹션에서 자세히 다룹니다.

설정 오버라이드 — CLI 플래그가 이긴다

일부 설정은 CLI 실행 시 플래그로 덮어쓸 수 있습니다. 예: --sandbox, --dangerously-skip-permissions.

• 설정 메뉴에는 오버라이드 출처 인디케이터가 표시됩니다. 예: Sandbox Mode  on (overridden by --sandbox).
• 이 인디케이터가 있으면, /config에서 디스크 값은 바꿀 수 있지만 현재 세션은 인자 우선이라 즉시 반영되지 않습니다. CLI를 재시작해야 적용됩니다.

2. 알아두면 좋은 빠른 팁

공식 문서가 강조하는 가장 자주 쓰이는 단축 동작과 명령 10가지를 정리했습니다. 손에 익혀두면 CLI에서의 작업 속도가 크게 빨라집니다.

3. 키바인딩

AGY CLI는 커스텀 키바인딩을 지원합니다. 두 가지 방법으로 변경할 수 있습니다.

• 인터랙티브 편집: 프롬프트에서 /keybindings 입력
• 직접 편집: ~/.gemini/antigravity-cli/keybindings.json 파일을 에디터로 수정

초기화 방법: keybindings.json 파일을 삭제하면 다음 실행 시 기본값으로 자동 복원됩니다.

기본 키바인딩 — 카테고리별 정리

① TUI / 세션 제어

② 명령 승인 (인터랙티브 프롬프트)

③ 텍스트 편집

④ 탐색 / 스크롤

키바인딩 커스터마이징 규칙

• 다중 매핑: 한 동작에 여러 키 조합을 매핑할 수 있습니다. JSON에서 배열로 지정.
• 비활성화: 특정 동작의 키 배열을 빈 배열 [] 로 두면 해당 단축키가 비활성화됩니다.
• 오류 복구: JSON이 망가져 있어도 CLI는 유효한 부분만 사용하고, 깨진 동작은 기본값으로 폴백합니다.

한눈 보기 요약

Antigravity CLI 공식 기능 정리

Antigravity 공식 문서 cli-features 페이지를 한국어로 정리. 플러그인·터미널 샌드박스·슬래시 명령 레퍼런스·서브에이전트 4개 축으로 구성됩니다.

1. 플러그인 (Plugins)

플러그인은 스킬·서브에이전트·룰·MCP 서버·훅을 하나의 네임스페이스가 부여된 번들로 묶은 배포 단위입니다. 설치 한 번으로 여러 종류의 커스터마이징을 한꺼번에 가져올 수 있습니다.

설치 시 동작

• CLI가 플러그인 파일을 사용자의 홈 디렉토리 아래 ~/.gemini/antigravity-cli/plugins/<plugin_name>/ 에 스테이징합니다.
• Antigravity 에이전트가 시작 시 이 위치를 자동 탐색해 플러그인을 로드합니다.

~/.gemini/antigravity-cli/
├── plugins/
│   └── <plugin_name>/
│       ├── plugin.json         # 필수 — 플러그인 마커
│       ├── mcp_config.json     # 선택 — MCP 서버 정의
│       ├── hooks.json          # 선택 — 이벤트 훅 정의
│       ├── skills/             # 선택 — 스킬 모음
│       ├── agents/             # 선택 — 서브에이전트 모음
│       └── rules/              # 선택 — 룰 모음
└── import_manifest.json        # 플러그인 추적 매니페스트

구성 요소 접근

플러그인이 스테이징·로드되면, CLI 안에서 슬래시 명령으로 각 구성 요소(스킬·에이전트·MCP·훅 등)와 상호작용할 수 있습니다. 예: /skills로 스킬 목록을 보거나 /mcp로 MCP 서버 상태를 확인.

2. 터미널 샌드박스 (Terminal Sandbox)

터미널 샌드박스는 에이전트가 로컬 셸 명령을 실행할 때 호스트 시스템을 보호하기 위한 경량 격리 메커니즘입니다. 잠재적으로 파괴적인 파일 조작이나 허가되지 않은 외부 네트워크 요청을 차단합니다.

왜 가상머신·컨테이너가 아닌가

VM이나 도커 컨테이너 대신 OS 네이티브 격리 기능을 사용해 시작 오버헤드를 사실상 0으로 유지합니다. 플랫폼별 백엔드는 다음과 같습니다.

설정 방법

사용자 설정 파일(~/.gemini/antigravity-cli/settings.json)에 다음 항목을 추가하면 활성화됩니다.

{
  "enableTerminalSandbox": true
}

• enableTerminalSandbox (boolean, 기본값 false) — 모든 로컬 에이전트 프로세스에 격리 경계를 강제합니다.

인터랙티브 승인 — 샌드박스 on/off에 따른 차이

에이전트가 사용자의 확인이 필요한 터미널 명령을 제안할 때, CLI의 승인 프롬프트는 현재 샌드박스 설정에 따라 동적으로 옵션을 추가합니다.

3. 슬래시 명령 레퍼런스

Antigravity CLI는 프롬프트 박스에 직접 입력하는 슬래시 명령으로 대화 관리·설정·에이전트 상태 조회를 처리합니다. 공식 문서가 강조하는 핵심 12개를 카테고리별로 정리했습니다.

settings.json을 통한 고급 커스터마이징

일부 슬래시 명령은 단순 토글을 넘어 ~/.gemini/antigravity-cli/settings.json에서 깊이 있는 설정을 받습니다.

세분화된 권한 — 전역 레벨 대신 명령 단위 화이트/블랙리스트

{
  "permissions": {
    "allow": ["command(git)", "command(npm test)"],
    "deny":  ["command(rm -rf)"]
  }
}

커스텀 상태 라인 / 윈도우 타이틀

에이전트의 실시간 메타데이터(JSON: 현재 디렉토리·활성 모델·토큰 사용량·상태 등)를 사용자가 작성한 셸 스크립트로 파이프해, 동적인 상태바나 터미널 타이틀을 만들 수 있습니다. 모니터링 패널을 직접 꾸미고 싶을 때 유용합니다.

4. 서브에이전트 (Subagents)

Antigravity CLI는 비동기 서브에이전트 프레임워크를 갖추고 있습니다. 메인 에이전트가 병렬 작업, 백그라운드 조사, 시스템 테스트를 위임할 수 있어 현재 진행 중인 대화를 멈추지 않고도 부가 작업을 끝낼 수 있습니다.

서브에이전트란?

• 독립된 동시 세션: 메인 대화와 별개로 돌아가는 에이전트 인스턴스
• 자동 스폰: 문서 조회, 빌드 실행, 수정 사항 검증 같은 백그라운드 작업이 필요하면 메인 에이전트가 알아서 서브를 띄움
• 풀 권한: 코드 검색, 파일 편집, 터미널 명령, 웹 검색까지 도구 전반에 접근 가능
• 권한 통제는 메인이 결정: 서브에이전트가 MCP 도구를 쓸 수 있는지, 파일을 쓸 수 있는지를 메인 에이전트가 게이트키퍼로 통제

/agents 패널 — 인터랙티브 관리 UI

• 열기: 프롬프트에 /agents 입력
• 개요 화면: 활성·완료 서브에이전트 목록 + 상태(running · done · killed 등) + 현재 실행 중인 단계 표시
• 상세 화면: 목록에서 항목을 선택하면 전체 대화 — 단계·생각·도구 실행 로그 — 가 풀스크린으로 표시

도구 승인 — 두 가지 경로

서브에이전트가 사용자 권한이 필요한 도구(예: 로컬 명령 실행, 파일 쓰기)를 호출하려 하면 승인 요청이 떠오릅니다. 두 가지 방식으로 처리할 수 있습니다.

요약 — 4개 축의 관계

Gemini CLI → Antigravity CLI 마이그레이션

Antigravity 공식 문서 gcli-migration 페이지를 한국어로 정리. 익스텐션·컨텍스트 파일·스킬·MCP 서버 4축의 이전 절차와 위치 변화를 다룹니다.

첫 실행 — Migration Options 화면

Antigravity CLI를 처음 실행하면 Migration Options 화면이 표시됩니다. 여기서 기존 Gemini CLI 익스텐션을 동등한 Antigravity 플러그인으로 자동 변환하도록 선택할 수 있습니다.

대부분의 사용자는 마이그레이션이 끝난 직후 기존 Gemini CLI 워크플로우 그대로 Antigravity CLI를 사용할 수 있습니다. 컨텍스트 파일과 글로벌 에이전트 스킬은 같은 위치에서 그대로 로드됩니다.

1. 익스텐션 (Extensions) → 플러그인 (Plugins)

Gemini CLI가 ‘익스텐션’이라 부르던 — 기능을 묶어서 공유하는 단위 — 개념은 이제 업계 표준 용어인 플러그인으로 정착됐습니다. Antigravity CLI는 이 플러그인을 1급 시민으로 지원합니다.

자동 마이그레이션

첫 실행 시 안내되는 옵션을 통해 자동으로 진행되며, 언제든 명령으로 다시 실행할 수도 있습니다.

agy plugin import gemini

임포트 로그 보는 법

위 명령을 실행하면 로컬에 설치된 각 익스텐션을 검색해 플러그인으로 변환합니다. 변환 로그는 다음과 같은 형태로 출력됩니다.

[ok]    conductor
        - skills      : skipped (not found)
        - agents      : skipped (not found)
        ✔ commands    : 6 processed (converted to skills)
        - mcpServers  : skipped (not found)
        - hooks       : skipped (not found)
[ok]    google-workspace
        ✔ skills      : 6 processed
        - agents      : skipped (not found)
        ✔ commands    : 4 processed (converted to skills)
        ✔ mcpServers  : 1 processed
        - hooks       : skipped (not found)

• ✔ processed: 정상적으로 플러그인으로 변환된 항목
• - skipped (not found): 원래 익스텐션에 해당 컴포넌트가 없어 건너뜀
• commands → skills: 익스텐션의 커스텀 명령은 스킬로 변환됨

2. 컨텍스트 파일 (Rules)

Gemini CLI와 동일한 컨텍스트 파일 메커니즘이 그대로 동작합니다. 이전 작업 없이 즉시 사용 가능합니다.

3. 에이전트 스킬 (Agent Skills)

에이전트 스킬은 Antigravity CLI에서도 그대로 동작합니다. /skills 명령으로 관리하는 것도 동일하고, 스킬이 슬래시 명령으로 노출되는 동작도 똑같습니다. 차이는 워크스페이스 스킬의 저장 위치뿐입니다.

4. MCP 서버

로컬·원격 MCP 서버 모두 지원되고, /mcp 관리 명령도 동일합니다. 가장 중요한 차이는 두 가지입니다.

1. MCP 서버 정의가 settings.json에서 분리되어 별도의 mcp_config.json 파일을 사용
2. 원격 MCP 서버의 URL 필드 이름이 url(또는 deprecated된 httpUrl)에서 serverUrl로 변경

마이그레이션 체크리스트

전체 마이그레이션을 빠짐없이 진행하기 위한 체크리스트입니다. 순서대로 진행하시면 안전합니다.

한눈 보기 요약 — 위치 변화 매트릭스

Antigravity CLI 설치

Antigravity CLI를 처음 설치하는 가이드입니다. 시스템 요구사항을 확인한 후 원하는 방법을 선택하세요. 기존 Gemini CLI를 쓰던 경우라면 자동 마이그레이션 안내도 참고하세요.

1. 시스템 요구사항

2. Node.js 사전 준비

Antigravity CLI는 Node.js 기반 도구입니다. node --version으로 현재 버전을 확인하고, 20.0.0 미만이거나 설치돼 있지 않다면 아래 방법 중 하나로 설치하세요.

node --version    # v20.0.0 이상이면 OK
npm  --version    # npm도 함께 설치돼 있어야 함

설치 옵션

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
# 터미널 재시작 후
nvm install --lts
nvm use --lts

# https://github.com/coreybutler/nvm-windows/releases 에서 설치 후
nvm install lts
nvm use lts

brew install node

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

choco install nodejs-lts

3. Antigravity CLI 설치 방법

방법 1 — npm 글로벌 설치 (권장)

가장 표준적인 방법입니다. 한 번 설치하면 어디서든 agy 명령으로 실행할 수 있습니다.

npm install -g @google/antigravity-cli

# 설치 확인
agy --version

방법 2 — Homebrew (macOS / Linux)

brew install antigravity-cli

방법 3 — 설치 없이 일회성 실행 (npx)

한 번만 써보고 싶거나 글로벌 설치를 피하고 싶을 때.

npx @google/antigravity-cli@latest

방법 4 — IDE에서 자동 설치

VS Code, Cursor, Windsurf 등 Antigravity IDE 또는 VS Code 계열 환경의 통합 터미널에서 처음 agy 를 입력하면 컴패니언 익스텐션과 함께 설치가 안내됩니다. 자세한 내용은 IDE 익스텐션 섹션 참조.

방법 5 — 제한된 환경 (Anaconda 등)

Node.js를 직접 설치할 수 없는 폐쇄망·랩 환경에서 유용합니다.

conda create -y -n agy_env -c conda-forge nodejs
conda activate agy_env
npm install -g @google/antigravity-cli

4. 첫 실행과 인증

설치가 끝났다면 빈 디렉토리든 작업 중인 프로젝트든 어디서나 agy 명령으로 진입할 수 있습니다.

agy
# 1) 환영 화면 표시
# 2) 처음 한 번 Google 계정 로그인 (브라우저 자동 오픈)
# 3) 기존 Gemini CLI 사용자라면 Migration Options 안내
# 4) /help 또는 /ide install 추천 표시

인증·계정·과금 통합 흐름의 자세한 안내는 인증 설정 섹션을 참고하세요. Workspace SSO를 쓰는 팀은 다음과 같이 도메인을 지정해 로그인합니다.

agy auth login --workspace example.com

5. 설치 결과 확인 체크리스트

아래 3가지가 모두 정상 응답하면 설치가 끝난 것입니다.

# 1. 버전
agy --version

# 2. 인증 상태
agy auth status

# 3. 한 줄 프롬프트 (헤드리스 모드)
agy -p "현재 디렉토리의 파일 구조를 한 줄로 요약해줘"

6. 업데이트와 제거

npm install -g @google/antigravity-cli@latest
# 또는
agy update

npm uninstall -g @google/antigravity-cli
# 설정 파일도 함께 제거하려면
rm -rf ~/.gemini/antigravity-cli

7. 설치 후 추천 다음 단계

문제 해결 — 자주 묻는 설치 오류

/config — 인터랙티브 설정 메뉴

CLI 안에서 settings.json을 직접 열지 않고도 자주 쓰는 설정을 즉시 토글할 수 있는 TUI 메뉴.

호출 방법

실행 중인 CLI 프롬프트에서 /config를 입력하면 다음과 같은 메뉴가 떠 현재 설정값을 한눈에 보여줍니다.

  Artifact Review      asks for review
  Editor               auto ($EDITOR)
  Enable Telemetry     on
  Non-Workspace Access off
  Notifications        off
  Rendering Mode       native terminal (inline)
  Sandbox Mode         off
  Show Tips            on
> Tool Permission      request-review
  Verbosity            high

  Controls whether terminal commands require your approval before running.

  ↑/↓ Navigate · enter Edit · Esc Clear Search/Exit

특정 항목에서 Enter를 누르면 선택지 목록이 열리고, 현재 적용 중인 값에 (current) 표시가 함께 보입니다.

Tool Permission
> request-review (current)
  proceed-in-sandbox
  always-proceed
  strict

각 항목 상세 (10종)

렌더링 모드 비교 — Native Terminal (inline) vs. No Flickering (altscreen)

settings.json과의 관계

/config로 변경한 값은 사용자 설정 파일(~/.gemini/settings.json 또는 ~/.antigravity/settings.json)에 즉시 기록됩니다. 따라서 동일한 변경을 텍스트 에디터로 직접 해도 결과는 같습니다. 어느 쪽이 편리한지에 따라 선택하세요.

자주 쓰는 조합

문제 해결

개발 환경 설정

Gemini CLI를 사용하기 위해 필요한 개발 도구를 설치하세요. Node.js, Git, uv(Python 패키지 매니저)의 역할과 설치 방법을 안내합니다.

Node.js — Gemini CLI의 핵심 런타임

설치 여부 확인

node --version   # 예: v22.11.0 (20.0.0 이상이면 OK)
npm --version    # 예: 10.9.0

명령어가 인식되지 않거나(command not found) 버전이 20.0.0 미만이면 아래 방법으로 설치하세요.

Set-ExecutionPolicy : 레지스트리 키 'HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\PowerShell\1\ShellIds\Microsoft.PowerShell'
에 대한 액세스가 거부되었습니다.
+ CategoryInfo          : PermissionDenied: (:) [Set-ExecutionPolicy], UnauthorizedAccessException
+ FullyQualifiedErrorId : System.UnauthorizedAccessException,Microsoft.PowerShell.Commands.SetExecutionPolicyCommand

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

# 변경 확인
Get-ExecutionPolicy -Scope CurrentUser   # → RemoteSigned

Set-ExecutionPolicy RemoteSigned
# Y 입력 후 Enter

# 단일 명령 우회 실행
powershell -ExecutionPolicy Bypass -Command "node --version"

# 한 세션 동안만 우회
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

설치 방법

방법 1: 공식 사이트 (가장 간단 — 추천)

https://nodejs.org에서 LTS(장기 지원) 버전을 다운로드하여 설치합니다. Node.js와 npm이 함께 설치됩니다.

처음 사용하시면 방법 1만 따라하세요. 아래 방법 2·3은 여러 Node 버전을 다뤄야 하거나 패키지 매니저를 선호하는 사용자를 위한 옵션입니다.

# nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

# 터미널 재시작 후
nvm install --lts
nvm use --lts

# nvm-windows 설치 후 (https://github.com/coreybutler/nvm-windows/releases)
nvm install lts
nvm use lts

brew install node

# NodeSource 저장소 추가 (최신 LTS: Node.js 22.x 기준)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

choco install nodejs-lts

Git — 버전 관리 및 Worktree 지원

설치 여부 확인

git --version   # 예: git version 2.43.0

설치 방법

설치 후 초기 설정

Git을 처음 설치했다면 사용자 정보를 설정하세요. 이 정보는 커밋 기록에 포함됩니다.

# 사용자 이름과 이메일 설정
git config --global user.name "이름"
git config --global user.email "email@example.com"

# 설정 확인
git config --list

uv — 초고속 Python 패키지 매니저

설치 여부 확인

uv --version   # 예: uv 0.6.12

설치 방법

macOS / Linux 설치

# 공식 설치 스크립트 (권장)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 설치 후 셸 재시작 또는
source $HOME/.local/bin/env

Windows 설치

# 공식 설치 스크립트
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

uv로 Python MCP 서버 실행하기 선택 · 예시 · 건너뛰어도 됨

↓ 아래 코드 블록은 참고용 예시입니다. 지금 따라 입력하지 마세요.

# [예시] Python으로 작성된 MCP 서버를 등록하는 한 가지 방법
# 실제로는 사용하려는 MCP 서버에 따라 명령이 완전히 달라집니다.
# 그리고 대부분의 MCP 서버는 Node.js(npx)로 실행되므로 uv 없이도 충분합니다.
gemini mcp add filesystem uvx mcp-server-filesystem /path/to/dir

# [예시] settings.json 직접 설정 — 동일한 결과
# "mcpServers": {
#   "filesystem": {
#     "command": "uvx",
#     "args": ["mcp-server-filesystem", "/path/to/dir"]
#   }
# }

전체 환경 검증

모든 도구가 설치되었는지 한 번에 확인하세요.

# 필수: Node.js 20+ 확인
node --version

# 필수: npm 확인
npm --version

# 권장: Git 확인
git --version

# 권장: uv 확인 (Python 스크립트 개발 · MCP 서버 실행은 선택)
uv --version

IDE 익스텐션

VS Code, Antigravity, Cursor, Windsurf 등 VS Code 계열 IDE에서 Gemini CLI를 IDE와 연동하세요.

Gemini CLI Companion 익스텐션이란?

gemini-cli-vscode-ide-companion(게시자: Google)은 통합 터미널에서 실행 중인 Gemini CLI에 현재 IDE의 컨텍스트를 자동으로 공유해주는 공식 확장입니다. 사용자가 매번 파일 경로를 복사·붙여넣기 하거나 코드를 인용하지 않아도, Gemini CLI가 IDE에서 열린 파일·선택 영역·커서 위치를 인식하고 변경 사항을 IDE의 diff 뷰어로 보여줍니다.

지원 IDE

VS Code 1.99.0 이상의 API를 사용하는 IDE에서 동작합니다.

주요 기능

요구사항

• VS Code 1.99.0 이상 또는 동일 API 레벨의 포크 IDE
• Gemini CLI가 별도 설치되어 있어야 함 — 설치 가이드 참조
• 익스텐션은 IDE의 통합 터미널에서 실행 중인 Gemini CLI 세션을 감지합니다. 외부 터미널에서는 동작하지 않습니다.

설치 방법

1. VS Code에서 설치

가장 간단한 방법입니다.

1. 왼쪽 사이드바의 익스텐션 아이콘 클릭 (또는 Cmd/Ctrl+Shift+X)
2. 검색창에 Gemini CLI 입력
3. 게시자가 Google인 Gemini CLI Companion 선택 → Install

2. Antigravity / Cursor / Windsurf / VSCodium에서 설치 (Open VSX)

이 IDE들은 Open VSX를 기본 마켓플레이스로 사용합니다. 익스텐션 탭에서 검색하면 같은 결과가 나오지만, 보이지 않을 경우 다음 방법을 사용합니다.

# 익스텐션 탭에서 정확한 ID로 검색
Google.gemini-cli-vscode-ide-companion

# 1. https://open-vsx.org/extension/Google/gemini-cli-vscode-ide-companion 에서
#    "Download" 버튼으로 .vsix 파일 다운로드

# 2. 명령행에서 설치 (각 IDE의 CLI 명령 사용)
code --install-extension gemini-cli-vscode-ide-companion-*.vsix       # VS Code
cursor --install-extension gemini-cli-vscode-ide-companion-*.vsix     # Cursor
windsurf --install-extension gemini-cli-vscode-ide-companion-*.vsix   # Windsurf
# Antigravity는 GUI에서 익스텐션 패널 → "..." 메뉴 → "Install from VSIX..." 선택

3. Gemini CLI 자동 설치 트리거

VS Code 계열 IDE의 통합 터미널에서 처음 gemini를 실행하면, CLI가 IDE를 감지하고 익스텐션 설치를 안내합니다. 또한 CLI 내부 슬래시 명령으로도 설치할 수 있습니다.

/ide install      # 현재 IDE에 맞는 companion 익스텐션 자동 설치
/ide status       # 연결 상태 확인
/ide enable       # IDE 모드 켜기 (기본값)
/ide disable      # IDE 모드 끄기 (컨텍스트 공유 중단)

사용법

1. IDE의 통합 터미널을 엽니다 (Ctrl+`)
2. gemini 실행 — 익스텐션이 활성 상태면 우측 상태바 또는 첫 응답에 IDE 연결 표시가 나옵니다
3. 편집기에서 코드를 선택한 뒤 프롬프트 작성 — 선택 영역이 자동으로 컨텍스트에 포함됩니다
4. AI가 파일 수정을 제안하면 IDE의 diff 뷰어가 열립니다 — 라인별로 승인/거부 가능

설정 및 문제 해결

> 현재 IDE(VS Code/Antigravity/Cursor)에 Gemini CLI Companion 익스텐션이 설치되어 있는지 확인하고, 없으면 /ide install로 설치해줘. 설치 후 /ide status로 연결 상태를 보고해줘.

빠른 시작

설치부터 첫 번째 대화까지 5분 안에 시작해보세요.

단계별 가이드

npm install -g @google/gemini-cli

cd my-project
gemini

> 이 프로젝트의 구조를 설명해줘
> README.md를 요약해줘
> src/ 폴더에서 TODO 주석을 찾아줘

기본 사용 패턴

대화형 모드 (기본)

# 대화형 REPL 시작
gemini

# 초기 프롬프트와 함께 시작
gemini "이 프로젝트에 대해 설명해줘"

비대화형 모드 (일회성 질문)

# 질문 후 바로 종료
gemini -p "README.md를 요약해줘"

# 파이프와 함께 사용
cat error.log | gemini -p "이 에러 로그를 분석해줘"

대화형 + 프롬프트

# 프롬프트 실행 후 REPL 유지
gemini -i "프로젝트 구조를 분석해줘"

# 모든 작업 자동 승인 (주의해서 사용)
gemini --approval-mode=yolo

# 파일 편집만 자동 승인
gemini --approval-mode=auto_edit

인증 설정

Gemini CLI에서 사용할 수 있는 인증 방법과 설정 방법을 알아봅니다.

인증 방법 전환: `/auth` 명령

REPL 내에서 /auth 명령을 입력하면 OAuth / API Key / Vertex AI 등 인증 방법을 대화형으로 전환할 수 있습니다. 새 방법을 선택하면 필요한 브라우저 로그인 또는 환경 변수 확인을 진행합니다.

/auth

인증 방법

1. Google 계정으로 로그인 (권장)

가장 간단한 방법입니다. gemini를 실행하고 "Sign in with Google"을 선택하면 브라우저를 통해 로그인이 진행됩니다. 인증 정보는 로컬에 캐시되어 이후 세션에서 자동으로 사용됩니다.

2. Gemini API 키

Google AI Studio에서 API 키를 발급받아 환경 변수로 설정합니다.

export GEMINI_API_KEY="your-api-key-here"

3. Vertex AI

Google Cloud 프로젝트를 통한 인증으로, 세 가지 방법을 지원합니다:

• A. ADC (Application Default Credentials — 애플리케이션 기본 인증 정보): gcloud auth application-default login 명령으로 설정
• B. 서비스 계정 키: JSON 키 파일 경로를 GOOGLE_APPLICATION_CREDENTIALS에 설정
• C. Google Cloud API 키: GOOGLE_API_KEY 환경 변수 사용 (일부 조직에서 제한될 수 있음)

Vertex AI 인증 시 다음 환경 변수도 설정이 필요합니다:

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="us-central1"

Google Cloud 프로젝트 설정

다음에 해당하는 경우 Google Cloud 프로젝트 설정이 필요합니다:

• 회사, 학교, Google Workspace 계정 사용자
• Gemini Code Assist 라이선스 보유자
• 엔터프라이즈 구독자

# 환경 변수로 프로젝트 설정 (공식: GOOGLE_CLOUD_PROJECT)
export GOOGLE_CLOUD_PROJECT="my-project-id"

환경 변수 영구 저장

두 가지 방법으로 환경 변수를 영구적으로 저장할 수 있습니다.

방법 1: 셸 설정 파일

export GEMINI_API_KEY="your-api-key-here"
export GOOGLE_CLOUD_PROJECT="my-project-id"

방법 2: .gemini/.env 파일

현재 디렉토리에서 상위로 탐색하며 첫 번째로 발견된 .gemini/.env 파일을 로드합니다. 홈 디렉토리의 ~/.gemini/.env도 지원됩니다.

GEMINI_API_KEY=your-api-key-here
GOOGLE_CLOUD_PROJECT=my-project-id

CLI 치트시트

자주 사용하는 명령어와 옵션을 한눈에 확인하세요.

기본 명령어

주요 옵션

REPL 내부 명령어

REPL(대화형 모드)에서 사용할 수 있는 슬래시(/) 명령어입니다. gemini를 실행한 후 아래 명령어를 입력하세요.

@ 명령 (파일/디렉토리 컨텍스트 주입)

프롬프트에 @로 시작하는 경로를 넣으면 해당 파일/디렉토리 내용이 즉시 프롬프트에 포함됩니다. 내부적으로 read_many_files 도구를 사용합니다.

# 단일 파일
@src/components/UserProfile.tsx 이 컴포넌트 설명해줘

# 여러 파일 체이닝
@src/types/User.ts @src/api/users.ts 두 파일이 일관성 있는지 확인해줘

# 디렉토리 전체
@src/utils/ 이 유틸리티들 deprecated API 쓰는지 확인해줘

# 공백 이스케이프
@My\ Documents/notes.md 요약해줘

# 외로운 @ — 그대로 모델로 전달
이 코드의 @ 심볼은 무엇을 의미하나?

• git-aware 필터링: 기본적으로 node_modules/, dist/, .env, .git/ 등 git-ignored 파일은 제외됨. context.fileFiltering 설정으로 변경 가능
• 대용량/바이너리: read_many_files가 성능을 위해 건너뛰거나 truncate할 수 있음

하네스 엔지니어링 (Harness Engineering)

LLM을 단순 호출하는 것을 넘어, "에이전트가 살아 움직이는 환경"을 설계하는 기술. Gemini CLI를 진짜 생산성 도구로 만드는 핵심 사고방식입니다.

하네스(Harness)란 무엇인가?

하네스(harness)는 원래 "마구(馬具)" — 말을 마차에 연결하는 가죽 끈을 뜻합니다. 소프트웨어에서는 "무언가를 통제 가능하게 묶어두는 장치"를 의미하며, AI 분야에서는 LLM을 둘러싼 실행 루프 + 도구 + 컨텍스트 + 안전장치의 총합을 가리킵니다.

같은 모델(예: Gemini 3 Pro)을 사용해도, 하네스가 어떻게 설계되었느냐에 따라 결과물의 품질이 10배 이상 차이가 납니다. 하네스 엔지니어링은 바로 이 차이를 만드는 작업입니다.

왜 Gemini CLI에서 중요한가?

Gemini CLI는 단순한 챗봇이 아니라 파일을 수정하고, 셸 명령을 실행하고, 외부 API를 호출하는 자율 에이전트입니다. 이런 에이전트가 안전하고 일관되게 동작하려면 다음 질문에 답할 수 있어야 합니다:

• 모델은 어떤 컨텍스트를 알아야 하는가? (코드 스타일, 도메인 지식, 금기 사항)
• 어떤 도구까지 사용해도 되는가? (셸 명령, 외부 API, 파일 시스템 접근)
• 어떤 작업이 승인 없이 자동 실행되어도 되고, 어떤 작업은 사람의 검토가 필요한가?
• 실수했을 때 어떻게 되돌리거나 격리할 것인가?
• 긴 작업의 상태와 메모리는 어떻게 유지할 것인가?

Gemini CLI는 이 질문들에 대응하는 9개 레이어의 하네스 컴포넌트를 제공합니다.

Gemini CLI 하네스의 9개 레이어

레이어를 직관적으로 이해하기

아래는 사용자가 "이 함수 리팩터링해줘"라고 입력했을 때, 9개 레이어가 차례로 작동하는 과정입니다:

사용자 입력
    │
    ▼
[1. 컨텍스트] ──── GEMINI.md 로드, 메모리 병합, 코드 스타일 주입
    │
    ▼
[2. 모델]    ──── 라우터가 작업 복잡도 판단 → Gemini 3 Pro 선택
    │
    ▼
[5. 제어]    ──── Plan Mode면 먼저 계획만, 일반 모드면 바로 실행
    │
    ▼
[6. 모듈화]  ──── "리팩터링" 스킬/서브에이전트가 있으면 위임
    │
    ▼
[3. 도구]    ──── read_file → edit → run_shell_command(테스트)
    │
    ▼
[4. 안전]    ──── 각 도구 호출마다 approval-mode/sandbox/policy 검사
    │
    ▼
[7. 상태]    ──── 변경 전 자동 체크포인트 저장 → 실패 시 /rewind
    │
    ▼
[9. 관측]    ──── 텔레메트리에 도구 호출, 토큰 사용량, 실패 기록

실전 튜닝 레시피

레시피 1: "처음 보는 레거시 프로젝트" 하네스

모델이 코드를 마구 수정하지 않고, 먼저 이해하고 계획부터 세우게 만드는 설정입니다.

# 읽기 전용으로 시작 → 안전하게 탐색
gemini --approval-mode=plan -m gemini-3-pro

# 계획이 마음에 들면 Shift+Tab으로 일반 모드 전환

+ GEMINI.md에 "먼저 코드 구조를 파악하고 변경 계획을 제시한 뒤, 사용자 승인 후 수정"이라는 메타 지침을 넣으면 더 안정적입니다.

레시피 2: "신뢰할 수 있는 작업 자동화" 하네스

CI 파이프라인이나 새벽 자동 작업 등, 사람이 지켜보지 않는 환경에서 동작하는 설정입니다.

# 격리된 컨테이너 + 자동 승인 + JSON 출력으로 로그 수집
gemini \
  --sandbox \
  --approval-mode=yolo \
  --output-format=json \
  --prompt "오늘 머지된 PR을 요약해서 release-notes.md 업데이트해줘"

레시피 3: "큰 작업을 작게 쪼개기" 하네스

한 에이전트에게 거대한 작업을 시키지 말고, 전문 서브에이전트에게 위임하는 패턴입니다.

---
name: code-reviewer
description: 코드 변경 사항을 보안·성능·가독성 관점에서 리뷰
tools: read_file, run_shell_command(git diff:*)
---
당신은 시니어 엔지니어입니다. diff를 받으면 다음 순서로 리뷰합니다:
1. 보안 이슈 (SQL injection, XSS, 인증)
2. 성능 핫스팟
3. 테스트 커버리지
한국어로 답하되, 코드 스니펫은 그대로 인용하세요.

메인 에이전트는 code-reviewer 서브에이전트에게 이 PR 리뷰 부탁해처럼 위임만 하면 됩니다. 컨텍스트가 분리되어 메인 세션의 토큰을 절약하고, 전문성도 높아집니다.

레시피 4: "되돌릴 수 있는 실험" 하네스

위험한 변경을 시도하기 전, 안전망을 깔아두는 설정입니다.

1. Git Worktree로 별도 브랜치에서 작업: gemini --worktree feat/experiment
2. 체크포인팅 활성화: settings.json에 "checkpointing": { "enabled": true }
3. 훅으로 위험 명령 차단: PreToolUse 훅에서 rm -rf / 같은 패턴 거부
4. 실패하면 /rewind로 직전 도구 호출 취소

안티패턴 (피해야 할 설정)

측정 가능한 하네스 품질 지표

좋은 하네스는 "감"이 아니라 숫자로 검증할 수 있습니다. 아래 지표를 주기적으로 추적하세요:

• 1차 시도 성공률 — 사용자 개입 없이 작업이 완료되는 비율
• 롤백률 — /rewind나 git reset으로 되돌린 비율 (낮을수록 좋음)
• 토큰/작업 비율 — 같은 작업을 더 적은 토큰으로 끝내는가 (캐싱·서브에이전트 효과)
• 승인 피로도 — 사용자가 승인 다이얼로그를 거부한 비율 (도구 권한 재설계 신호)
• 탈선(off-track) 빈도 — 의도하지 않은 파일을 수정한 빈도 (컨텍스트/스킬 부족 신호)

> 이 프로젝트의 GEMINI.md, .gemini/settings.json, .gemini/hooks/, .gemini/agents/, .gemini/skills/ 파일을 모두 읽고
"하네스 엔지니어링" 9개 레이어 관점에서 부족한 부분을 표로 정리해줘.
각 레이어별로 (현재 상태 / 권장 개선 / 우선순위) 컬럼을 채워줘.

참고 자료

• Gemini CLI 공식 문서 — 각 레이어 컴포넌트의 상세 레퍼런스
• CLI 레퍼런스 — --approval-mode, --sandbox 등 하네스 관련 플래그 전체
• Sandboxing, Policy Engine, Hooks — 안전 레이어 구성 가이드

GEMINI.md (프로젝트 컨텍스트)

프로젝트별 지시사항과 규칙을 정의하여 AI의 응답을 맞춤화하세요.

GEMINI.md란?

GEMINI.md는 Gemini 모델에게 프로젝트에 대한 컨텍스트와 지시사항을 전달하는 파일입니다. 매번 프롬프트에 반복적인 설명을 입력하는 대신, 한 번 정의하면 모든 세션에서 자동으로 적용됩니다.

계층 구조

Gemini CLI는 다음 순서로 컨텍스트 파일을 로드합니다:

GEMINI.md 작성 예시

# 프로젝트: My TypeScript Library

## 일반 지침
- 기존 코딩 스타일을 따를 것
- 함수와 클래스에 JSDoc 주석 추가
- 한국어로 주석 작성

## 코딩 스타일
- 들여쓰기: 2칸 스페이스
- 인터페이스 이름: 'I' 접두사 사용
- 엄격한 동등 비교 (=== 및 !==)
- 세미콜론 필수

## 테스트
- Jest 프레임워크 사용
- 테스트 파일은 __tests__ 디렉토리에 배치
- 커버리지 80% 이상 유지

모듈화

@ 구문으로 다른 마크다운 파일을 임포트할 수 있습니다.

@./components/instructions.md
@../shared/style-guide.md

파일명 커스터마이징

settings.json에서 컨텍스트 파일명을 변경할 수 있습니다.

{
  "context": {
    "fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]
  }
}

> 현재 프로젝트의 .gemini/settings.json에서 Gemini CLI가 AGENTS.md, CONTEXT.md, GEMINI.md를 컨텍스트 파일로 읽도록 설정해줘. 파일이 없으면 만들고, 기존 설정은 유지하면서 context.fileName 배열을 추가하거나 갱신해줘.

관련 명령어

Auto-Memory 실험적

Auto-Memory는 과거 세션 기록을 분석해 반복되는 워크플로우를 자동으로 Agent Skill로 추출하는 실험적 기능입니다. 백그라운드에서 세션 시작 시 실행되며, 3시간 이상 유휴 상태였고 사용자 메시지가 10개 이상인 세션만 분석합니다.

{
  "experimental": {
    "autoMemory": true
  }
}

> 현재 프로젝트의 .gemini/settings.json에서 Gemini CLI Auto-Memory를 활성화해줘. 파일이 없으면 만들고, 기존 설정은 유지하면서 experimental.autoMemory 값을 true로 설정해줘. 적용 후 CLI 재시작이 필요한지도 알려줘.

• 활성화 후 CLI를 재시작해야 합니다.
• 추출된 스킬 후보는 /memory inbox로 검토하고 승격/삭제할 수 있습니다.
• 승격된 스킬은 ~/.gemini/skills/(사용자) 또는 .gemini/skills/(워크스페이스)로 이동합니다.
• 비활성화는 autoMemory를 false로 설정 후 재시작.

내부 동작 5단계

1. 적격성 스캔: ~/.gemini/tmp/<project>/chats/의 최근 세션 인덱싱. 3시간+ 유휴 + 10+ 사용자 메시지인 세션만 적격.
2. 락 획득: 프로젝트 메모리 디렉토리에 락 파일을 두어 다중 CLI 인스턴스 사이에 한 번만 추출하도록 조정.
3. 서브 에이전트 추출: confucius 전용 서브 에이전트(Flash 프리뷰 모델)가 세션을 검토하고 SKILL.md 초안 작성. 증거가 약하면 아무것도 만들지 않는 것이 기본.
4. 패치 검증: 기존 스킬 편집 제안 시 unified diff .patch 파일 생성 → dry-run 후 깨끗하게 적용되지 않으면 폐기.
5. 알림: 새 스킬/패치 생성 시 인라인 메시지로 대기 항목 수 표시.

인박스 액션

/memory inbox 다이얼로그에서:

• Read — 전체 SKILL.md 본문 검토
• Promote — 사용자(~/.gemini/skills/) 또는 워크스페이스(.gemini/skills/) 디렉토리로 승격
• Discard — 원하지 않는 스킬 폐기
• Apply / Reject — 기존 스킬에 대한 .patch 제안 적용/거부

모델 선택

작업 특성에 맞는 최적의 모델을 선택하는 방법을 알아봅니다.

사용 가능한 모델

모델 선택 방법

CLI 시작 시 지정

# Pro 모델로 시작
gemini -m pro

# Flash 모델로 시작
gemini -m flash

세션 중 변경

/model

대화형 다이얼로그가 열리며 모델을 선택할 수 있습니다. 변경은 즉시 적용됩니다.

모델 선택 가이드

에이전트 스킬

전문 지식과 워크플로우를 패키징하여 AI의 능력을 확장하세요.

에이전트 스킬이란?

에이전트 스킬은 특화된 전문 지식과 절차적 워크플로우를 패키징한 확장 기능입니다. GEMINI.md와 달리 스킬은 온디맨드로 작동하며, 모델이 작업의 관련성과 스킬의 설명을 기반으로 자율적으로 활성화를 결정합니다.

주요 장점

스킬 발견 우선순위

같은 이름의 스킬이 여러 위치에 있을 때 높은 우선순위가 낮은 우선순위를 오버라이드합니다:

1. 워크스페이스 스킬 (최우선): .gemini/skills/ 또는 .agents/skills/ — 보통 버전 컨트롤에 커밋해 팀과 공유
2. 사용자 스킬: ~/.gemini/skills/ 또는 ~/.agents/skills/ — 모든 워크스페이스에서 사용 가능한 개인 스킬
3. 확장 프로그램 스킬: 설치된 확장 프로그램에 번들된 스킬

즉 Workspace > User > Extension.

스킬 관리 명령어

슬래시 명령 스코프

/skills disable / /skills enable은 기본 user 스코프입니다. 워크스페이스 설정만 관리하려면 --scope workspace 추가:

/skills disable my-skill                    # user 스코프
/skills disable my-skill --scope workspace  # workspace 스코프

내장 skill-creator로 자동 생성

새 스킬을 만드는 가장 빠른 방법은 자연어로 요청하는 것입니다:

> create a new skill called 'code-reviewer'

Gemini CLI가 내장 skill-creator를 사용하여 자동으로:

1. 스킬 디렉토리 생성 (예: code-reviewer/)
2. name/description 프론트매터가 있는 SKILL.md 작성
3. 표준 리소스 디렉토리(scripts/, references/, assets/) 생성

SKILL.md 구조

각 스킬 폴더의 루트에 SKILL.md가 필수로 있어야 하며, YAML 프론트매터의 두 필드가 필수입니다:

---
name: pdf-fixer             # 필수. 고유 식별자 (디렉토리명과 일치 권장)
description: PDF 병합/분할/OCR 처리. 사용자가 PDF 파일 작업을 요청할 때 사용.  # 필수
---

# 본문 (마크다운)
이 스킬이 어떻게 동작해야 하는지에 대한 지침을 작성합니다.

권장 디렉토리 구조 (SKILL.md 외 폴더는 모두 선택):

my-skill/
├── SKILL.md      (필수)
├── scripts/      (실행 스크립트)
├── references/   (참조 문서)
└── assets/       (템플릿, 데이터)

활성화 5단계

MCP 서버

Model Context Protocol을 통해 외부 도구와 API를 Gemini CLI에 연동하세요.

MCP 서버란?

MCP(Model Context Protocol) 서버는 Gemini CLI에 외부 도구와 리소스를 제공하는 애플리케이션입니다. 외부 시스템, API, 데이터베이스, 커스텀 워크플로우에 대한 접근을 가능하게 합니다.

전송 방식

MCP 서버 추가

CLI로 추가

# Stdio 기반 서버 추가
gemini mcp add github npx -y @modelcontextprotocol/server-github

# HTTP 기반 서버 추가
gemini mcp add api-server http://localhost:3000 --transport http

# 환경 변수와 함께 추가
gemini mcp add slack node server.js --env SLACK_TOKEN=xoxb-xxx

# 특정 도구만 포함
gemini mcp add github npx -y @modelcontextprotocol/server-github \
  --include-tools list_repos,get_pr

# 사용자 범위(글로벌)로 추가 — 모든 프로젝트에서 사용 가능
gemini mcp add db node db-server.js --scope user

실전 튜토리얼: GitHub MCP 서버 (Docker)

가장 인기 있는 MCP 서버 중 하나인 GitHub MCP 서버를 설치하는 전체 흐름:

1. 토큰 준비: fine-grained PAT 생성. 권한: Metadata/Contents Read, Issues/PR Read/Write
2. 환경 변수 설정:

   export GITHUB_PERSONAL_ACCESS_TOKEN="github_pat_..."

3. settings.json 추가:

   {
     "mcpServers": {
       "github": {
         "command": "docker",
         "args": [
           "run", "-i", "--rm",
           "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
           "ghcr.io/github/github-mcp-server:latest"
         ],
         "env": {
           "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
         }
       }
     }
   }

4. CLI 재시작 후 /mcp list → ✓ github: docker ... - Connected 확인
5. 자연어 사용: "List the open PRs in the google/gemini-cli repository." → 에이전트가 자동으로 mcp_github_list_pull_requests 호출

settings.json으로 설정

Python 서버 (Stdio)

{
  "mcpServers": {
    "pythonTools": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "env": { "API_KEY": "$DB_TOKEN" },
      "timeout": 15000
    }
  }
}

HTTP 서버

{
  "mcpServers": {
    "httpServer": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": { "Authorization": "Bearer token" }
    }
  }
}

Docker 기반 서버

{
  "mcpServers": {
    "dockerized": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "my-mcp-server:latest"]
    }
  }
}

> 현재 프로젝트의 .gemini/settings.json에 MCP 서버를 추가해줘. 서버 이름은 내도구, 실행 명령은 여기에 입력할게: [실행 명령]. 파일이 없으면 만들고, 기존 mcpServers 설정은 유지한 채 새 서버만 추가해줘.

MCP 설정 필드 전체

전송 방식별 필수 필드

trust vs 사용자 승인

• trust: settings.json에 고정된 사전 설정. 해당 서버의 모든 도구가 항상 승인 없이 실행됨.
• user-approved: 세션 내 동적으로 추가되는 허용 목록. 도구별 또는 서버별로 단일/영구 승인 가능.

서버 관리

보안

• 환경 변수 필터링: *TOKEN*, *SECRET*, *PASSWORD*, *KEY* 등 민감한 변수는 자동으로 제거됩니다.
• 명시적 전달: 필요한 변수는 env 블록에서 명시적으로 설정해야 합니다.
• OAuth 지원: 동적 검색, 자동 토큰 갱신, ~/.gemini/mcp-oauth-tokens.json에 안전한 저장.

샌드박싱

AI 작업을 격리된 환경에서 안전하게 실행하세요.

샌드박싱이란?

샌드박스(Sandbox)는 "모래놀이터"라는 뜻으로, 프로그램을 나머지 시스템과 격리된 안전한 공간에서 실행하는 보안 기술입니다. AI가 실수로 중요한 파일을 삭제하거나 시스템을 손상시키는 것을 방지합니다.

샌드박싱은 잠재적으로 위험한 작업을 호스트 시스템으로부터 격리하는 보안 기능입니다. AI 작업과 실행 환경 사이에 보안 장벽을 제공하여 우발적인 시스템 손상을 방지합니다.

플랫폼별 격리 방식

활성화 방법

우선순위 순서로 세 가지 방법이 있습니다:

1. 명령줄 플래그

gemini -s
# 또는
gemini --sandbox

2. 환경 변수

export GEMINI_SANDBOX=true
# 특정 방식 지정 — 전체 허용 값 목록
export GEMINI_SANDBOX=docker         # Docker 컨테이너
export GEMINI_SANDBOX=podman         # Podman 컨테이너
export GEMINI_SANDBOX=sandbox-exec   # macOS Seatbelt
export GEMINI_SANDBOX=runsc          # gVisor (Linux)
export GEMINI_SANDBOX=lxc            # LXC/LXD (Linux 실험적)

3. settings.json

{
  "tools": {
    "sandbox": true
  }
}

Docker 기본 이미지 & 커스텀화

• 기본 이미지: ghcr.io/google/gemini-cli:latest
• 워크스페이스 마운트: 현재 작업 디렉토리가 호스트와 동일한 절대 경로로 컨테이너에 마운트됩니다 (예: 호스트 /Users/you/project → 컨테이너 /Users/you/project)

커스텀 이미지 — 옵션 A: 레지스트리 이미지

{
  "tools": {
    "sandbox": {
      "command": "docker",
      "image": "us-central1-docker.pkg.dev/my-project/my-repo/my-custom-sandbox:latest"
    }
  }
}

또는 환경 변수: export GEMINI_SANDBOX_IMAGE="us-central1-docker.pkg.dev/.../my-sandbox:latest"

커스텀 이미지 — 옵션 B: Dockerfile 자동 빌드

1. 프로젝트 루트에 .gemini/sandbox.Dockerfile 작성
2. gh CLI 설치/인증 (기본 ghcr.io/google/gemini-cli 베이스 이미지 사용 시)
3. BUILD_SANDBOX=1 환경 변수와 함께 실행:

BUILD_SANDBOX=1 GEMINI_SANDBOX=docker gemini -p "run my custom build"

> 현재 프로젝트의 .gemini/settings.json에 샌드박싱을 활성화하는 설정을 추가해줘. 파일이 없으면 새로 만들고, 이미 다른 설정이 있으면 유지한 채 tools.sandbox 값을 true로 설정해줘.

macOS Seatbelt 프로파일

SEATBELT_PROFILE 환경 변수로 6가지 프로파일 중 선택할 수 있습니다. 기본값은 permissive-open입니다.

도구 수준 vs 프로세스 수준

도구 수준 샌드박싱은 개별 작업(셸 명령, 파일 쓰기)만 격리하며, 비도구 작업은 로컬 환경과 통합을 유지합니다. security.toolSandboxing: false로 비활성화할 수 있습니다.

훅 (Hooks)

에이전트 루프의 특정 시점에서 커스텀 스크립트를 실행하여 동작을 제어하세요.

훅(Hook)은 "갈고리"라는 뜻으로, 프로그램이 실행되는 중간 지점에 여러분의 코드를 "걸어 놓는" 기능입니다. 예를 들어 "AI가 응답하기 직전에 이 스크립트를 실행해줘"처럼 특정 순간에 자동으로 동작을 추가할 수 있습니다.

훅이란?

훅은 Gemini CLI의 에이전트 루프에서 특정 시점에 실행되는 스크립트입니다. 소스 코드를 수정하지 않고도 동작을 커스터마이징할 수 있습니다. 훅은 동기적으로 실행되며, 모든 훅이 완료될 때까지 Gemini CLI가 대기합니다.

훅 이벤트

설정 예시

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "write_file|replace",
        "hooks": [
          {
            "name": "security-check",
            "type": "command",
            "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/security.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

> 현재 프로젝트에 Gemini CLI 훅을 설정해줘. .gemini/hooks 폴더를 만들고, 파일 수정 도구 실행 전에 동작하는 BeforeTool 훅 예시 스크립트를 만든 뒤 .gemini/settings.json의 hooks 설정에 등록해줘. 기존 설정은 유지해줘.

종료 코드

stdin JSON 입력 구조

모든 훅 스크립트는 다음 공통 필드를 stdin으로 받습니다:

도구 훅(BeforeTool/AfterTool)은 추가로 tool_name, tool_input 필드를 받습니다.

훅 설정 필드

훅 공통 출력 필드 (stdout JSON)

이벤트별 입출력 필드

BeforeTool / AfterTool

• 입력: tool_name, tool_input, mcp_context, original_request_name (tail 호출용)
• BeforeTool 출력:
  • decision: "deny" — 도구 실행 차단 (reason 필수, 에이전트가 재시도 가능)
  • hookSpecificOutput.tool_input — 모델 인자에 머지+오버라이드
  • 종료 코드 2 — stderr이 거부 사유, 턴은 계속
• AfterTool 출력:
  • decision: "deny" — 결과를 에이전트에게 숨김 (reason이 결과 대체)
  • hookSpecificOutput.additionalContext — 결과에 추가 텍스트
  • hookSpecificOutput.tailToolCallRequest: { name, args } — 다른 도구 자동 호출 (프로그래매틱 라우팅). 결과가 원래 응답 대체

BeforeAgent / AfterAgent

• BeforeAgent:
  • decision: "deny" — 턴 차단 + 메시지 폐기 (히스토리에 미저장)
  • continue: false — 턴 차단 + 메시지 히스토리에 저장
  • hookSpecificOutput.additionalContext — 이 턴에만 프롬프트에 추가
• AfterAgent:
  • 입력: prompt, prompt_response, stop_hook_active
  • decision: "deny" — 응답 거부 + 자동 재시도 (reason이 새 프롬프트)
  • continue: false — 재시도 없이 세션 중지
  • hookSpecificOutput.clearContext — LLM 메모리 비우되 UI 표시 유지

MCP 도구 매처 패턴

MCP 서버 도구는 mcp_<server_name>_<tool_name> 패턴으로 명명됩니다. 훅 matcher에서 정규식으로 활용:

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "mcp_github_.*",
        "hooks": [{ "type": "command", "command": "/path/to/gh-audit.sh" }]
      }
    ]
  }
}

환경 변수

훅 실행 시 다음 환경 변수에 접근할 수 있습니다:

• GEMINI_PROJECT_DIR: 프로젝트 루트 절대 경로
• GEMINI_SESSION_ID: 현재 세션 고유 식별자
• GEMINI_CWD: 현재 작업 디렉토리
• GEMINI_PLANS_DIR: 플랜 파일 저장 디렉토리 절대 경로
• CLAUDE_PROJECT_DIR: 호환성 별칭 (GEMINI_PROJECT_DIR과 동일 값)

관리 명령어

/hooks list             # 설정된 훅 목록 표시 (별칭: /hooks show, /hooks panel)
/hooks enable-all       # 모든 훅 활성화
/hooks disable-all      # 모든 훅 비활성화
/hooks enable <이름>     # 특정 훅 활성화
/hooks disable <이름>    # 특정 훅 비활성화

위협 모델 (출처별 신뢰 수준)

주요 위험: 임의 코드 실행, 데이터 유출(API 키 등), 프롬프트 인젝션

📊 데이터 분석 후크 예시 실전

훅의 stdin JSON 입력을 활용하면 사용자 개입 없이 도구 호출, 토큰 소비, 파일 변경 빈도 등을 수집해 나중에 분석할 수 있습니다. 아래는 즉시 적용 가능한 4가지 분석 후크 레시피입니다.

① 도구 호출 로그 (JSONL 누적)

모든 도구 호출을 한 줄짜리 JSON으로 누적합니다. jq로 즉시 쿼리 가능.

#!/usr/bin/env bash
set -euo pipefail
LOG=".gemini/analytics/tool-calls.jsonl"
mkdir -p "$(dirname "$LOG")"

# stdin JSON에 timestamp + cwd를 추가해 JSONL 1줄로 append
jq -c --arg ts "$(date -u +%FT%TZ)" \
   '. + {ts: $ts, project: env.GEMINI_PROJECT_DIR}' \
  >> "$LOG"

{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "*",
        "hooks": [
          { "name": "log-tool-calls", "type": "command",
            "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/log-tool-calls.sh",
            "timeout": 2000 }
        ]
      }
    ]
  }
}

분석 쿼리 예시:

# 가장 많이 사용된 도구 Top 10
jq -r '.tool_name' .gemini/analytics/tool-calls.jsonl | sort | uniq -c | sort -rn | head

# 시간대별 도구 호출 분포
jq -r '.ts[11:13]' .gemini/analytics/tool-calls.jsonl | sort | uniq -c

# 오늘 셸 명령 호출 모두
jq -r 'select(.tool_name=="run_shell_command") | .tool_input.command' \
  .gemini/analytics/tool-calls.jsonl | tail -20

② 파일 변경 빈도 (hot files)

AfterTool에서 파일 편집 도구만 골라 변경된 경로를 카운트합니다. 자주 수정되는 "핫스팟" 파일을 식별할 수 있습니다.

#!/usr/bin/env bash
set -euo pipefail
LOG=".gemini/analytics/file-edits.csv"
mkdir -p "$(dirname "$LOG")"
[ -f "$LOG" ] || echo "timestamp,tool,file,session_id" > "$LOG"

INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
SESSION=$(echo "$INPUT" | jq -r '.session_id')

case "$TOOL" in
  write_file|replace|edit)
    FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty')
    [ -n "$FILE" ] && \
      echo "$(date -u +%FT%TZ),$TOOL,$FILE,$SESSION" >> "$LOG"
    ;;
esac

"AfterTool": [
  { "matcher": "write_file|replace|edit",
    "hooks": [
      { "name": "track-file-edits", "type": "command",
        "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/track-file-edits.sh" }
    ]
  }
]

핫스팟 분석:

# 가장 자주 수정된 파일 Top 10
cut -d, -f3 .gemini/analytics/file-edits.csv | sort | uniq -c | sort -rn | head

③ 세션별 토큰·비용 추적

AfterModel은 LLM 호출마다 응답 메타데이터를 받습니다. 토큰 사용량을 세션별로 누적해 비용을 추정합니다.

#!/usr/bin/env bash
set -euo pipefail
LOG=".gemini/analytics/tokens.jsonl"
mkdir -p "$(dirname "$LOG")"

jq -c '{
  ts: (now | strftime("%FT%TZ")),
  session_id,
  model: (.model_name // "unknown"),
  prompt_tokens:     (.usage.prompt_tokens     // 0),
  completion_tokens: (.usage.completion_tokens // 0),
  cached_tokens:     (.usage.cached_tokens     // 0)
}' >> "$LOG"

비용 추정 (Gemini 3 Pro 가정, 1M 토큰당 USD):

# 세션별 토큰 합계
jq -s 'group_by(.session_id) | map({
  session: .[0].session_id,
  prompt:     map(.prompt_tokens)     | add,
  completion: map(.completion_tokens) | add,
  cached:     map(.cached_tokens)     | add
}) | sort_by(.prompt + .completion) | reverse' \
  .gemini/analytics/tokens.jsonl

# 오늘 사용 토큰 총합
jq -s "map(select(.ts | startswith(\"$(date -u +%F)\"))) |
       {prompt: map(.prompt_tokens) | add,
        completion: map(.completion_tokens) | add}" \
  .gemini/analytics/tokens.jsonl

④ 위험 명령·실패율 모니터링

BeforeTool로 위험한 셸 패턴을 기록(또는 차단)하고, AfterTool로 실패율을 집계합니다.

#!/usr/bin/env bash
# BeforeTool: run_shell_command 매처에만 부착
LOG=".gemini/analytics/shell-audit.jsonl"
mkdir -p "$(dirname "$LOG")"

INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // ""')

# 위험 패턴 매칭
RISK="low"
case "$CMD" in
  *"rm -rf"*|*"sudo "*|*"dd if="*|*"chmod 777"*)         RISK="high"   ;;
  *"git push --force"*|*"DROP TABLE"*|*"DROP DATABASE"*)  RISK="high"   ;;
  *"curl "*"| sh"*|*"curl "*"| bash"*)                    RISK="high"   ;;
  *"npm install -g"*|*"pip install"*)                     RISK="medium" ;;
esac

echo "$INPUT" | jq -c --arg risk "$RISK" \
  '{ts: (now | strftime("%FT%TZ")), cmd: .tool_input.command, risk: $risk, session_id}' \
  >> "$LOG"

# RISK=high는 차단하려면 아래 주석 해제 (exit 2 = 사용자에게 거부 메시지)
# [ "$RISK" = "high" ] && { echo "🚫 위험 명령 차단: $CMD" >&2; exit 2; }

exit 0

대시보드 한 줄 요약:

# 오늘 risk 등급별 명령 개수
jq -r --arg today "$(date -u +%F)" \
  'select(.ts | startswith($today)) | .risk' \
  .gemini/analytics/shell-audit.jsonl | sort | uniq -c

#!/usr/bin/env bash
# .gemini/hooks/daily-report.sh — SessionStart에 부착
REPORT=".gemini/analytics/daily/$(date -d 'yesterday' +%F).md"
[ -f "$REPORT" ] && exit 0   # 이미 생성됨
mkdir -p "$(dirname "$REPORT")"

cat > "$REPORT" <<EOF
# $(date -d 'yesterday' +%Y-%m-%d) Gemini CLI 사용 리포트

## 도구 호출
$(jq -r --arg d "$(date -d 'yesterday' +%F)" \
   'select(.ts | startswith($d)) | .tool_name' \
   .gemini/analytics/tool-calls.jsonl | sort | uniq -c | sort -rn)

## 토큰 사용량
$(jq -s --arg d "$(date -d 'yesterday' +%F)" \
   'map(select(.ts | startswith($d))) |
    {prompt: map(.prompt_tokens) | add, completion: map(.completion_tokens) | add}' \
   .gemini/analytics/tokens.jsonl)
EOF
echo "📊 어제 리포트 생성: $REPORT"

echo ".gemini/analytics/" >> .gitignore

모범 사례

성능

• 병렬 실행: 순차 fetch 대신 Promise.all로 병렬
• 캐싱: 빈번히 호출되는 후크(BeforeTool/AfterModel)는 .gemini/hook-cache.json으로 결과 저장
• 이벤트 선택: AfterAgent는 턴당 1회, AfterModel은 청크마다 호출 — 최종 응답만 검사하면 AfterAgent 사용
• matcher 좁히기: "*" 대신 "write_file|replace"처럼 구체적으로

독립 테스트

CLI에 연결 전 샘플 JSON으로 후크 동작 검증:

# 테스트 입력 생성
cat > test-input.json << 'EOF'
{
  "session_id": "test-123",
  "cwd": "/tmp/test",
  "hook_event_name": "BeforeTool",
  "tool_name": "write_file",
  "tool_input": {"file_path": "test.txt", "content": "Test"}
}
EOF

# 후크 실행 + 종료 코드 확인
cat test-input.json | .gemini/hooks/my-hook.sh
echo "Exit code: $?"

실행 권한

• macOS/Linux: chmod +x .gemini/hooks/*.sh
• Windows PowerShell: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

비활성 후크 (settings.json)

슬래시 명령 외에도 hooks.disabled 배열로 직접 비활성화:

{
  "hooks": {
    "disabled": ["my-hook-name", "another-hook"]
  }
}

{
  "security": {
    "environmentVariableRedaction": {
      "enabled": true,
      "allowed": ["MY_REQUIRED_TOOL_KEY"]
    }
  }
}

파일 관리

Gemini CLI를 사용하여 파일을 읽고, 생성하고, 수정하는 방법을 알아봅니다.

파일 작업 예시

# 파일 읽기 및 분석
> src/index.ts 파일을 분석해줘

# 파일 생성
> utils/helpers.ts에 문자열 유틸리티 함수를 만들어줘

# 파일 수정
> config.json에서 포트를 3000에서 8080으로 변경해줘

# 여러 파일 작업
> src/ 폴더의 모든 .ts 파일에서 console.log를 제거해줘

# 파일 검색
> TODO 주석이 포함된 파일을 모두 찾아줘

승인 모드

Gemini CLI는 파일을 수정하기 전에 사용자의 승인을 요청합니다.

# 승인 모드 지정
gemini --approval-mode auto_edit

# yolo 모드 (모든 작업 자동 승인)
gemini --approval-mode yolo

# --yolo / -y 플래그는 deprecated (하위 호환을 위해 동작하나 권장하지 않음)
# gemini -y  ← 대신 --approval-mode=yolo 사용 권장

셸 명령어

Gemini CLI 내에서 직접 셸 명령을 실행하고 결과를 활용하세요.

셸 명령 실행

Gemini CLI는 AI가 필요할 때 자동으로 셸 명령을 실행합니다. 또한 사용자가 직접 실행을 요청할 수도 있습니다.

# AI에게 명령 실행 요청
> git log --oneline -10 실행해서 최근 커밋 보여줘
> npm test 실행하고 실패한 테스트 수정해줘
> docker ps로 실행 중인 컨테이너 확인해줘

# 파이프로 결과 전달
cat build.log | gemini -p "빌드 에러를 분석하고 해결 방법을 알려줘"

비대화형 자동화

# CI/CD 파이프라인에서 사용
gemini -p "src/ 폴더의 코드를 린트하고 문제를 수정해줘" -y

# 스크립트에서 사용
result=$(gemini -p "package.json의 버전을 파싱해줘" -o json)
echo $result

JSON 출력 스키마

--output-format=json은 단일 객체를 반환합니다:

Stream JSON (JSONL) 이벤트

--output-format=stream-json은 줄바꿈 구분 이벤트를 스트리밍합니다:

종료 코드

세션 관리

대화 세션을 저장하고 이어서 작업하는 방법을 알아봅니다.

세션 이어하기

# 가장 최근 세션 재개 (인자 없이)
gemini --resume

# 인덱스 번호로 재개
gemini --resume 1

# 세션 UUID로 재개
gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890

# 세션 재개 + 추가 프롬프트
gemini --resume 1 "이 PR을 마무리해줘"

REPL 내부 인터랙티브 브라우저

실행 중인 세션에서 /resume을 입력하면 과거 대화를 미리보기, 검색, 선택할 수 있는 인터랙티브 세션 브라우저가 열립니다.

세션 목록 및 관리

# 현재 프로젝트의 세션 목록
gemini --list-sessions

# 특정 세션 삭제
gemini --delete-session 0

저장 위치 및 보존 정책

• 저장 경로: ~/.gemini/tmp/<project_hash>/chats/ — 프로젝트별로 격리된 디렉토리에 대화, 도구 실행, 토큰 사용량, 추론 요약이 함께 저장됩니다.
• 자동 정리: 기본 30일 후 자동 삭제. general.sessionRetention.maxAge 설정으로 조정 가능.
• 세션당 턴 제한: maxSessionTurns로 컨텍스트 비용을 제한할 수 있습니다.

확장 프로그램

Gemini CLI의 기능을 확장하는 확장 프로그램을 설치하고 관리하세요.

확장 프로그램 관리

install 플래그 전체

new 템플릿 종류

• mcp-server — MCP 서버 기반 확장 (도구 추가용)
• context — 컨텍스트 파일 위주 확장
• custom-commands — 슬래시 명령 위주 확장

개발용 명령어

# 새 확장 프로그램 템플릿 생성
gemini extensions new ./my-extension

# 로컬 확장 프로그램 링크 (개발용)
gemini extensions link /path/to/extension

# 확장 프로그램 구조 검증
gemini extensions validate ./my-extension

> Gemini CLI 확장 프로그램을 설치하고 활성화하는 명령어를 만들어줘. 확장 프로그램 소스는 [Git URL 또는 로컬 경로]이고, 설치 후 목록 확인과 enable 명령까지 함께 알려줘.

작업 자동화

Gemini CLI를 스크립트와 CI/CD(지속적 통합/지속적 배포 — 코드 변경 시 자동으로 테스트하고 배포하는 자동화 시스템) 파이프라인에 통합하여 작업을 자동화하세요.

Headless 모드

Gemini CLI를 프로그래밍 방식으로 사용할 수 있습니다. 대화형 인터페이스 없이 프롬프트를 처리합니다.

# 비대화형 실행
gemini -p "모든 테스트 파일에 JSDoc 주석을 추가해줘" -y

# JSON 출력
gemini -p "package.json의 의존성 목록" -o json

# 파이프라인에서 사용
git diff HEAD~1 | gemini -p "이 변경사항을 리뷰해줘" -o text

CI/CD 활용 예시

name: AI Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @google/gemini-cli
      - run: |
          git diff origin/main...HEAD | \
          gemini -p "PR 변경사항을 리뷰하고 문제를 보고해줘" -y
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

스크립트 통합

#!/bin/bash
# 자동 코드 리뷰 스크립트

# 변경된 파일 목록 가져오기
changed_files=$(git diff --name-only HEAD~1)

# 각 파일에 대해 리뷰 수행
for file in $changed_files; do
  echo "리뷰 중: $file"
  gemini -p "다음 파일의 코드를 리뷰해줘: $file" -y -o text
done

랄프 루프 (Ralph Loop) 패턴

"같은 프롬프트를 무한 반복"이라는 단순한 아이디어로 거대한 작업을 끝내는 자율 에이전트 패턴. Gemini CLI의 헤드리스 모드와 자동 승인 모드만 있으면 누구나 구성할 수 있습니다.

랄프 루프란?

랄프 루프(Ralph Loop)는 호주 엔지니어 Geoffrey Huntley가 2025년에 공개·정착시킨 자율 에이전트 운용 패턴입니다. 이름은 미국 만화 〈심슨 가족〉의 캐릭터 Ralph Wiggum이 같은 말을 끝없이 반복하는 모습에서 따왔습니다.

핵심 아이디어는 어이없을 정도로 단순합니다:

왜 무한 반복이 효과적인가?

"한 번에 끝내면 되지 왜 반복하나?"라고 생각할 수 있지만, 랄프 루프는 LLM 에이전트의 구조적 약점 3가지를 정면으로 해결합니다:

덤으로, 사용자는 루프가 도는 동안 자유롭게 자리를 비울 수 있습니다. 노트북을 닫고 산책을 다녀와서 git diff로 결과를 검토하면 됩니다.

구성 요소

랄프 루프는 단 4개의 부품으로 동작합니다:

최소 구현 (5분 만에 시작하기)

1단계: 프롬프트 파일 작성

에이전트가 매 반복마다 따를 변하지 않는 지시문입니다. 구체적인 작업 목록은 여기에 적지 말고, "fix_plan.md를 읽고 다음 한 가지를 하라"는 메타 지시만 적습니다.

# 임무
당신은 이 저장소를 안전하게 개선하는 자율 에이전트입니다.

## 매 반복 절차
1. fix_plan.md를 읽는다. 없으면 빈 상태로 시작한다.
2. 가장 위에 있는 미완료 항목 **단 한 가지**를 선택한다.
3. 항목이 너무 크면 더 작은 단위로 쪼개서 fix_plan.md를 갱신만 하고 종료한다.
4. 항목이 적당하면 실제로 코드를 수정하고 npm test(또는 프로젝트의 테스트 명령)를 실행한다.
5. 테스트가 통과하면 fix_plan.md에서 해당 항목을 ✅로 표시한다.
6. 테스트가 실패하면 fix_plan.md 맨 아래에 새로운 작업 "테스트 실패 수정: [내용]"을 추가하고 종료한다.
7. 모든 작업이 ✅이면 STOP 파일을 만들고 종료한다.

## 절대 규칙
- git push 금지. 커밋만 한다.
- fix_plan.md 외 메타 파일은 만들지 않는다.
- 한 반복에 파일 5개 이상 동시에 수정하지 않는다.
- 의심스러우면 fix_plan.md에 질문을 적고 종료한다.

2단계: 초기 작업 목록

# Fix Plan

- [ ] src/auth/ 모듈에 단위 테스트 추가
- [ ] README의 깨진 링크 수정
- [ ] TypeScript strict 모드 켜고 발생한 에러 정리
- [ ] CI 워크플로우에 lint 단계 추가
- [ ] CHANGELOG.md 최신 커밋 기준으로 갱신

3단계: 루프 스크립트

#!/usr/bin/env bash
set -u

ITER=0
MAX_ITER=${MAX_ITER:-50}     # 안전장치: 최대 반복 횟수
LOG_DIR=".ralph-logs"
mkdir -p "$LOG_DIR"

while [ ! -f STOP ] && [ "$ITER" -lt "$MAX_ITER" ]; do
  ITER=$((ITER + 1))
  echo "===== 🔁 Iteration $ITER  $(date '+%H:%M:%S') ====="

  gemini \
    --approval-mode=yolo \
    --output-format=json \
    -p "$(cat PROMPT.md)" \
    > "$LOG_DIR/iter-$ITER.json" 2>&1

  # 짧은 휴식 (rate limit 회피)
  sleep 5
done

if [ -f STOP ]; then
  echo "✅ STOP 파일 감지 — 작업 완료"
  rm STOP
else
  echo "⚠️  최대 반복 횟수($MAX_ITER) 도달 — 수동 확인 필요"
fi

4단계: 실행

chmod +x ralph.sh
./ralph.sh

이게 전부입니다. 이제 자리를 비워도 됩니다.

중급 패턴: 병렬 랄프

여러 작업을 동시에 굴리고 싶다면 Git Worktree로 격리한 뒤 N개의 루프를 동시에 돌리는 병렬 랄프(Parallel Ralph)로 확장할 수 있습니다.

#!/usr/bin/env bash
# 3개 작업을 별도 worktree에서 동시 진행

TASKS=(
  "feat/auth-tests:auth 모듈 테스트 보강"
  "fix/typescript-strict:strict 모드 에러 정리"
  "docs/changelog-update:CHANGELOG 갱신"
)

for entry in "${TASKS[@]}"; do
  branch="${entry%%:*}"
  goal="${entry#*:}"
  wt="../ralph-${branch//\//-}"

  git worktree add "$wt" -b "$branch"
  (
    cd "$wt"
    cp ../$(basename "$PWD")/PROMPT.md .
    echo "# Goal\n$goal\n\n## Tasks\n- [ ] 시작" > fix_plan.md
    bash ../$(basename "$PWD")/ralph.sh > "../$wt.log" 2>&1 &
  )
done

wait
echo "✅ 모든 병렬 랄프 종료"

완료 후 각 worktree에 가서 git diff main으로 변경을 검토하고 PR을 따로 올립니다.

프롬프트 작성 비결 (가장 중요한 부분)

루프 자체는 단순하지만, PROMPT.md의 품질이 결과를 결정합니다. 실전에서 검증된 5가지 원칙:

① "다음 한 가지(One Next Thing)" 원칙

여러 작업을 한 반복에 끝내려고 하면 컨텍스트가 폭발합니다. 매 반복은 단 하나의 변경만 하도록 강제하세요.

❌ "fix_plan.md의 모든 항목을 처리하라"
✅ "fix_plan.md에서 가장 위 미완료 항목 단 한 가지만 처리하라"

② "쪼개기 vs 실행하기"를 분리

큰 작업을 만나면 즉시 시도하지 말고 먼저 쪼개기만 하고 종료하게 합니다. 다음 반복에서 작아진 항목으로 다시 시작합니다.

3. 항목이 너무 크면 더 작은 단위로 쪼개서 fix_plan.md를 갱신만 하고 종료한다.

③ 실패도 작업으로 만든다

테스트가 실패해도 멈추지 않고 새로운 작업으로 추가합니다. 다음 반복에서 fresh attention으로 디버그합니다.

6. 테스트가 실패하면 fix_plan.md 맨 아래에 새로운 작업 "테스트 실패 수정: [내용]"을 추가하고 종료한다.

④ 의심스러우면 멈춘다

에이전트가 확신하지 못할 때 추측으로 진행하면 잘못된 코드가 누적됩니다. fix_plan.md에 질문을 적고 종료하게 만들면 사람이 다음 날 답해주면 됩니다.

- 의심스러우면 fix_plan.md에 질문을 적고 종료한다.

⑤ 종료 조건을 명시한다

루프가 영원히 돌면 안 됩니다. STOP 파일이라는 명시적 신호를 두면 에이전트가 작업 완료를 직접 선언할 수 있습니다.

7. 모든 작업이 ✅이면 STOP 파일을 만들고 종료한다.

관측과 디버깅

루프가 돌면서 무슨 일이 벌어지는지 보고 싶다면 다음을 활용하세요:

• JSON 로그: --output-format=json으로 매 반복 결과를 구조화 저장. jq로 조회 가능
  Terminal복사

  # 마지막 반복에서 실행된 도구 호출만 추출
  jq -r '.tool_calls[] | "\(.name): \(.args)"' .ralph-logs/iter-12.json

• git log 모니터링: 다른 터미널에서 watch -n 5 'git log --oneline -10'으로 진행 상황 실시간 추적
• fix_plan.md diff: watch -n 10 'git diff fix_plan.md'로 계획 변화 추적
• 훅으로 알림: AfterAgent 훅에서 osascript -e 'display notification "iteration done"'(macOS) 호출

흔한 실수와 함정

언제 쓰면 좋고, 언제 피해야 하나

> 이 프로젝트에 랄프 루프(Ralph Loop)를 셋업해줘. 다음을 만들어줘:
> 1. PROMPT.md — fix_plan.md를 읽고 다음 한 가지만 처리하는 메타 지시문
> 2. fix_plan.md — README와 package.json을 분석해 시작 작업 5개 제안
> 3. ralph.sh — gemini --approval-mode=yolo --output-format=json 사용,
>    MAX_ITER=50, STOP 파일 감지, .ralph-logs/ 디렉토리에 로그 저장
> 4. .gitignore에 .ralph-logs/와 STOP 추가
> 5. 실행 전 확인사항을 README의 새 섹션 "Ralph Loop 운용"에 작성
> 안전을 위해 먼저 git worktree를 만들고 그 안에서 동작하도록 안내해줘.

참고 자료

• Geoffrey Huntley — "Ralph Wiggum as a software engineer" (원글)
• Gemini CLI 헤드리스 모드 — 랄프 루프의 실행 기반
• Git Worktrees — 격리 실행 환경
• Sandboxing — 자동 승인 모드의 안전장치
• 하네스 엔지니어링 — 더 큰 그림에서의 루프 설계

GitHub CLI 연동 (gh)

GitHub CLI(gh)를 Gemini CLI와 함께 사용해 이슈·PR·릴리스를 터미널에서 자동화하세요.

설치

최신 설치 가이드: github.com/cli/cli#installation

인증

# 대화형 OAuth 로그인 (브라우저 자동 오픈)
gh auth login

# 토큰 기반 로그인 (CI/CD)
echo "$GITHUB_TOKEN" | gh auth login --with-token

# 인증 상태 확인
gh auth status

# 다른 호스트 (GitHub Enterprise)
gh auth login --hostname github.mycompany.com

인증 정보는 OS 키체인(macOS Keychain / Windows Credential Manager / Linux libsecret)에 저장됩니다.

이슈 관리

# 새 이슈 작성 (대화형)
gh issue create

# 본문 파일에서 작성 (자동화 친화)
gh issue create --title "버그: 로그인 실패" --body-file issue.md --label bug

# 이슈 목록 (필터링)
gh issue list --label "kind/bug" --state open --limit 20
gh issue list --assignee @me

# 특정 이슈 조회
gh issue view 123              # 브라우저
gh issue view 123 --web

# 이슈 닫기/재오픈/댓글
gh issue close 123 --comment "Fixed in #456."
gh issue reopen 123
gh issue comment 123 --body "확인 부탁드립니다."

Pull Request 관리

# 현재 브랜치로 PR 생성 (HEREDOC으로 본문)
gh pr create --title "feat: 새 기능 추가" --body "$(cat <<'EOF'
## 요약
- 새 X 기능 추가
- Y 버그 수정

## 테스트
- [ ] 단위 테스트 통과
- [ ] 수동 검증

Closes #123
EOF
)"

# PR 목록 / 조회
gh pr list --state open --label "ready-to-review"
gh pr view 456
gh pr view 456 --web

# PR 체크아웃 (리뷰용)
gh pr checkout 456

# PR 머지 (4가지 전략)
gh pr merge 456 --merge          # merge commit
gh pr merge 456 --squash         # squash and merge
gh pr merge 456 --rebase         # rebase and merge
gh pr merge 456 --auto --squash  # CI 통과 후 자동 머지

# 브랜치 정리
gh pr merge 456 --squash --delete-branch

# 리뷰
gh pr review 456 --approve
gh pr review 456 --request-changes --body "..."
gh pr review 456 --comment --body "..."

저장소 / 워크플로우 / 릴리스

# 저장소
gh repo create my-project --public --source=. --push   # 로컬 → 신규 GitHub 저장소
gh repo clone owner/repo
gh repo fork owner/repo --clone

# Actions 워크플로우
gh workflow list
gh workflow view ci.yml
gh workflow run release.yml -f version=v1.2.3   # 입력값 전달
gh run list --workflow=ci.yml --limit 10
gh run view 12345 --log                          # 전체 로그
gh run watch                                      # 진행 중인 run 실시간 모니터

# 릴리스
gh release create v1.0.0 --generate-notes
gh release create v1.0.0 ./dist/*.tar.gz --notes-file CHANGELOG.md
gh release list
gh release download v1.0.0

Gemini CLI와 통합 패턴

패턴 1: 코드 리뷰 자동 요청

Gemini CLI로 작업 후 gh로 PR 생성을 한 번에:

> src/auth/ 모듈을 리팩토링하고, 변경사항을 새 브랜치에 커밋한 다음
> gh pr create로 PR을 만들어줘. PR 본문에는 변경 사항 요약과
> "Closes #142"를 포함해줘.

패턴 2: 이슈를 GEMINI.md 컨텍스트로 주입

# 이슈 본문을 그대로 Gemini에 전달
gh issue view 123 --json title,body --jq '"# \(.title)\n\n\(.body)"' \
  | gemini -p "이 이슈를 분석하고 구현 플랜을 만들어줘"

# 여러 이슈를 한꺼번에
gh issue list --label bug --json number,title,body --limit 5 \
  | gemini -p "이 버그들의 공통 원인을 찾아줘"

패턴 3: PR diff 자동 리뷰

gh pr diff 456 | gemini -p "이 PR의 보안·성능 문제점을 찾아 인라인 코멘트로 정리해줘"

패턴 4: 자동화 스크립트

#!/usr/bin/env bash
PR=$1
# 1) PR 가져와서 체크아웃
gh pr checkout "$PR"
# 2) Gemini로 분석
gh pr diff "$PR" | gemini -p "주요 변경 사항 요약" -o text > /tmp/summary.md
# 3) 리뷰 코멘트로 게시
gh pr review "$PR" --comment --body-file /tmp/summary.md

패턴 5: /setup-github 슬래시 명령

Gemini CLI 안에서 /setup-github를 실행하면 이슈 트리아지/PR 리뷰용 GitHub Actions 워크플로우를 자동 생성합니다 (Gemini CLI 자체에 내장된 명령).

주요 환경 변수

유용한 옵션

확장 (gh extension)

# 검색·설치
gh extension search
gh extension install owner/gh-extension-name

# 추천 확장 예
gh extension install dlvhdr/gh-dash       # 대시보드 TUI
gh extension install seachicken/gh-poi    # 머지된 로컬 브랜치 정리
gh extension install meiji163/gh-notify   # 알림 관리

# 업데이트 / 제거
gh extension upgrade --all
gh extension remove gh-dash

설정 파일

settings.json으로 Gemini CLI의 동작을 세밀하게 제어하세요.

설정 파일 위치

설정 파일은 두 위치에 저장됩니다. 워크스페이스(프로젝트) 설정이 사용자 설정을 덮어씁니다:

병합은 아래 → 위 순서로 덮어쓰기 방식이며, 배열/객체(예: mcpServers)는 각 단계에서 머지됩니다. CLI 인자 > 환경 변수 > 설정 파일의 큰 틀을 기억하세요.

주요 최상위 키

환경 변수 치환 구문

settings.json과 gemini-extension.json의 문자열 값에서 환경 변수를 치환할 수 있습니다:

민감 환경 변수 자동 리댁션

도구 실행 시 변수 이름에 다음 키워드가 포함되면 자동으로 가려집니다(best effort):

TOKEN · SECRET · PASSWORD · KEY · AUTH · CREDENTIAL · PRIVATE · CERT

{
  "security": {
    "environmentVariableRedaction": {
      "enabled": true,
      "allowed": ["PUBLIC_API_KEY"],
      "blocked": ["MY_CUSTOM_SECRET_VAR"]
    }
  }
}

텔레메트리 옵트아웃 (privacy)

기본적으로 익명화된 도구 이름, API 요청 메타데이터, 세션 설정이 수집됩니다. 프롬프트, 응답, 파일 내용은 수집되지 않습니다. 완전히 비활성화하려면:

{
  "privacy": {
    "usageStatisticsEnabled": false
  }
}

> 현재 프로젝트의 .gemini/settings.json을 확인해서 내가 원하는 Gemini CLI 설정을 추가해줘. 파일이 없으면 만들고, 기존 설정은 유지해줘. 원하는 설정은 다음과 같아: [여기에 원하는 기능과 값을 적기]

자주 쓰는 general 설정

설정 예시

{
  "ui": {
    "theme": "dark"
  },
  "model": {
    "name": "auto"
  },
  "context": {
    "fileName": ["GEMINI.md"]
  },
  "tools": {
    "sandbox": false
  },
  "security": {
    "toolSandboxing": true
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      }
    }
  },
  "hooks": {}
}

권한 (Permissions)

5개 보안 레이어를 한눈에 — 어떤 레이어가 무엇을 막는지, 언제 무엇을 켜야 하는지, 그리고 프롬프트 한 줄로 한 번에 설정하는 법.

5개 보안 레이어 비교

Gemini CLI는 자율 에이전트입니다 — 파일을 직접 수정하고 셸 명령을 실행합니다. 위험을 줄이기 위해 다음 5개 레이어가 겹쳐 동작합니다:

의사결정 가이드: 어떤 레이어부터 켤까?

모든 레이어를 한꺼번에 켤 필요는 없습니다. 상황별로 다음 순서를 권장합니다:

처음 사용자
   ↓
[1] 승인 모드 = default (기본값, 모든 도구 확인)
   ↓ "매번 확인이 귀찮다"
[2] 신뢰 폴더 등록 + 승인 모드 = auto_edit
   ↓ "셸 명령 중 위험한 패턴만 막고 싶다"
[3] 정책 엔진 + 위험 패턴 deny 규칙
   ↓ "yolo 모드로 자율 실행하고 싶다"
[4] 샌드박스(docker/seatbelt) + 강력한 정책
   ↓ "팀 전체에 적용 + 감사 로그 필요"
[5] 훅 기반 동적 차단 + 분석 로그

레이어별 한 줄 요약

1. 승인 모드 — 4가지 중 선택

세션 중 Shift+Tab으로 default → auto_edit → plan 순환. 영구 설정은 general.defaultApprovalMode. yolo 차단은 security.disableYoloMode = true.

2. 신뢰 폴더 — 디렉토리 단위 허용

처음 진입한 폴더에서 "이 폴더를 신뢰합니까?" 다이얼로그가 뜹니다. 신뢰한 폴더는 자동 도구 실행이 허용됩니다.

• REPL 내: /permissions trust
• CLI 일회성: gemini --skip-trust
• 여러 폴더 일괄 관리: ~/.gemini/trustedFolders.json

자세한 설정과 비신뢰 폴더 제한 사항 → 신뢰 폴더 전용 페이지

3. 정책 엔진 — 도구·인자 패턴 단위 규칙

도구 단위가 아니라 "도구 + 인자 패턴" 단위로 허용/거부할 수 있는 정밀 시스템. TOML 포맷으로 작성하며 우선순위로 충돌 해결.

[[rule]]
toolName = "run_shell_command"
commandPrefix = "rm -rf"
decision = "deny"
priority = 100

전체 문법, 매처 옵션(mcpName/mode/commandPrefix 등), 파일 위치 → 정책 엔진 전용 페이지

4. 샌드박스 — 실행 환경 자체를 격리

위 1~3이 "무엇을 허용/거부"라면 샌드박스는 "설사 잘못 실행되어도 호스트는 안전"한 마지막 방어선입니다.

GEMINI_SANDBOX=docker gemini --approval-mode=yolo   # 컨테이너 격리
GEMINI_SANDBOX=sandbox-exec gemini                  # macOS Seatbelt

6가지 macOS Seatbelt 프로파일, GEMINI_SANDBOX 값, 커스텀 이미지 → 샌드박싱 전용 페이지

5. 훅 기반 차단 — 동적 스크립트 거부

BeforeTool 후크에서 exit 2를 반환하면 모델에게 "거부됨, 다른 방법 시도"가 전달됩니다. 패턴 매칭으로 차단할 수도 있고, ML 분석 결과를 기반으로 조건부 차단할 수도 있습니다.

구현 예시(위험 명령 감사 + 차단) → 훅(Hooks) §④ 위험 명령·실패율 모니터링

💬 프롬프트로 한 번에 설정

JSON/TOML을 직접 작성하기 부담스럽다면, 아래 4가지 프롬프트를 채팅창에 그대로 붙여넣으세요. Gemini CLI가 알아서 파일을 만들고 병합합니다.

레시피 1 — "안전한 기본값" 한 번에 적용

> 이 프로젝트에 보수적인 권한 기본값을 설정해줘:
> 1. .gemini/settings.json 에 다음 키를 추가/병합:
>    - general.defaultApprovalMode = "auto_edit"
>    - security.folderTrust.enabled = true
>    - security.disableYoloMode = true
>    - security.environmentVariableRedaction.enabled = true
> 2. .gemini/policies/safety.toml 을 만들어:
>    - run_shell_command 의 rm -rf, sudo, dd, chmod 777 패턴 → deny
>    - write_file 의 .env, secrets/, credentials.json → deny
>    - write_file/replace 기본은 ask_user (우선순위 낮게)
> 3. .gitignore 에 .gemini/analytics/, .gemini/tmp/ 추가
> 작업 후 변경한 내용을 표로 요약해줘.

레시피 2 — "yolo 안전망" (worktree + 샌드박스 + 훅)

> yolo 모드를 안전하게 쓸 수 있는 환경을 만들어줘:
> 1. git worktree로 별도 브랜치(experimental/yolo) 생성
> 2. 그 worktree의 .gemini/settings.json 에:
>    - "security.toolSandboxing" = true
>    - "general.defaultApprovalMode" = "yolo"
> 3. .gemini/hooks/block-dangerous.sh 작성 (BeforeTool 부착):
>    - rm -rf /, git push --force, sudo, curl | sh 패턴은 exit 2 차단
> 4. GEMINI_SANDBOX=docker 로 실행하는 README.yolo.md 작성

레시피 3 — 팀 공유 정책 파일

> 팀 전체가 따를 .gemini/policies/team.toml 을 작성해줘:
> - 읽기 전용 도구(read_file, glob, search_file_content) → allow (priority 10)
> - npm/pnpm/yarn 의 test/lint/build 스크립트 → allow (priority 50)
> - git 의 status/diff/log/show → allow, 그 외 git 명령 → ask_user
> - production/, .env*, *.pem, *.key 쓰기 → deny (priority 1000)
> - 그 외 모든 도구 → ask_user
> 각 규칙에 왜 그렇게 분류됐는지 주석을 달아줘.

레시피 4 — 현재 권한 상태 자동 점검

> 이 프로젝트의 권한 설정을 점검해줘:
> 1. .gemini/settings.json, ~/.gemini/settings.json,
>    .gemini/policies/*.toml, ~/.gemini/policies/*.toml,
>    ~/.gemini/trustedFolders.json, .gemini/hooks/* 모두 읽기
> 2. 5개 권한 레이어 각각의 현재 상태를 정리
> 3. "안전(🟢) / 보통(🟡) / 위험(🔴)" 등급으로 평가
> 4. 개선 제안과 함께 .gemini/permissions-audit.md 로 저장

권장 프리셋 (상황별 조합)

테마

Gemini CLI의 터미널 UI를 취향에 맞게 커스터마이징하세요.

테마 설정

공식 키 경로는 ui.theme 입니다. settings.json에서 다음과 같이 설정합니다:

{
  "ui": {
    "theme": "dark"
  }
}

Gemini CLI는 /theme 명령어로 다양한 테마를 선택하거나 settings.json에서 테마명을 직접 지정할 수 있습니다.

사용 가능한 테마

커스텀 테마 정의

settings.json의 ui.customThemes 블록에서 색상을 직접 정의할 수 있습니다:

{
  "ui": {
    "customThemes": {
      "MyCustomTheme": {
        "name": "MyCustomTheme",
        "type": "custom",
        "background": {
          "primary": "#181818",
          "diff.added": "#1a3328",
          "diff.removed": "#3d2e0a"
        },
        "text": {
          "primary": "#f0f0f0",
          "secondary": "#a0a0a0",
          "link": "#5599ff",
          "accent": "#fdd663",
          "response": "#ffffff"
        },
        "border": {
          "default": "#333333",
          "focused": "#5599ff"
        }
      }
    }
  }
}

• text: primary(기본 텍스트), secondary(보조), link(URL), accent(강조), response(모델 응답)
• background: primary(주 배경), diff.added/diff.removed(diff 라인)
• border: default(기본), focused(포커스)

커스텀 명령어

자주 사용하는 프롬프트를 슬래시 명령어로 등록하세요.

커스텀 명령어란?

자주 사용하는 프롬프트 패턴을 슬래시 명령어로 만들어 빠르게 재사용할 수 있습니다.

파일 위치 및 우선순위

커스텀 명령어는 TOML 파일(.toml)로 정의하며 두 위치에서 자동 로드됩니다:

1. 프로젝트: <프로젝트 루트>/.gemini/commands/
2. 사용자: ~/.gemini/commands/

같은 이름의 명령이 양쪽에 있으면 프로젝트 명령이 우선합니다. 하위 디렉토리는 콜론(:)으로 네임스페이스가 됩니다:

• ~/.gemini/commands/test.toml → /test
• .gemini/commands/git/commit.toml → /git:commit

TOML 필드

인자 및 특수 구문

예시

description = "현재 diff 리뷰"
prompt = """
다음 변경사항을 리뷰하고 잠재적 문제점을 지적해줘.

!{git diff HEAD~1}

추가 지시사항: {{args}}
"""

무시 파일 (.geminiignore)

AI가 접근하지 않아야 할 파일과 디렉토리를 지정하세요.

.geminiignore란?

.gitignore와 유사한 형식으로, Gemini CLI가 무시할 파일과 디렉토리 패턴을 지정합니다. 민감한 파일, 대용량 바이너리, 불필요한 종속성 폴더 등을 제외할 수 있습니다.

예시

# 종속성
node_modules/
vendor/

# 빌드 산출물
dist/
build/
*.min.js

# 민감한 파일
.env
.env.local
credentials.json
*.pem

# 대용량 파일
*.zip
*.tar.gz
data/

요금 및 할당량

Gemini CLI의 무료 사용 한도와 유료 플랜을 확인하세요.

무료 사용

개인 유료 플랜

조직/기업 플랜

종량제

• Vertex AI (일반 모드): 모델과 토큰 사용량에 따라 과금. 동적 공유 쿼터 또는 사전 구매 처리량 옵션.
• Gemini API 키 (유료): 가격 등급별 가변 쿼터. 토큰/호출 단위 과금.

사용량 확인

/stats model 명령으로 현재 세션의 토큰 사용량과 적용된 한도를 실시간으로 확인할 수 있습니다. 세션 종료 시에도 사용량 요약이 자동으로 표시됩니다.

/stats model

키보드 단축키

Gemini CLI를 더 빠르게 사용하기 위한 단축키 모음입니다.

세션 제어

앱 제어

입력 편집

실행 취소 / 다시 실행

멀티라인 입력

컨텍스트별 특수 키

슬래시(/) 명령어

문제 해결

자주 발생하는 문제와 해결 방법을 안내합니다.

설치 관련

Node.js 버전 오류

Node.js 20.0.0 이상이 필요합니다.

# 현재 버전 확인
node --version

# nvm으로 업그레이드
nvm install 20
nvm use 20

권한 오류 (npm)

# npm 글로벌 디렉토리 변경
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 재설치
npm install -g @google/gemini-cli

인증 관련

로그인이 안 될 때

• 인터넷 연결을 확인하세요.
• 방화벽이나 프록시 설정을 확인하세요.
• Gemini Code Assist 지원 지역인지 확인하세요.

API 키 오류

• 환경 변수가 올바르게 설정되었는지 확인: echo $GEMINI_API_KEY
• API 키가 유효한지 Google AI Studio에서 확인하세요.

MCP 서버 관련

서버가 연결되지 않을 때

• 명령어와 인수가 올바른지 확인하세요.
• 서버를 독립적으로 테스트하세요.
• 실행 권한을 확인하세요.

도구가 발견되지 않을 때

• MCP 프로토콜이 올바르게 구현되었는지 확인하세요.
• 서버 로그를 검토하세요.

기업 네트워크 인증서 문제

UNABLE_TO_GET_ISSUER_CERT_LOCALLY 또는 unable to get local issuer certificate 오류가 발생할 때:

# 시스템 인증서 저장소 사용 (먼저 시도)
export NODE_USE_SYSTEM_CA=1

# 또는 명시적 CA 인증서 경로
export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt

# Windows PowerShell
$env:NODE_USE_SYSTEM_CA=1
$env:NODE_EXTRA_CA_CERTS="C:\path\to\corporate-ca.crt"

기업 방화벽이 SSL/TLS 트래픽을 가로채고 커스텀 CA 인증서가 필요할 때 사용. NODE_USE_SYSTEM_CA를 먼저 시도하고 안 되면 NODE_EXTRA_CA_CERTS 사용.

CI 환경 자동 감지 이슈

CI_TOKEN 같은 CI_ 프리픽스 환경 변수가 있으면 인터랙티브 모드 진입이 차단됩니다.

• 감지 트리거: CI, CONTINUOUS_INTEGRATION, CI_* 프리픽스
• 일시 해제: env -u CI_TOKEN gemini
• 비대화형 강제: CI=true gemini -p "..."

MCP EADDRINUSE 오류

MCP 서버 시작 시 EADDRINUSE (Address already in use) 발생 시:

# Linux/macOS — 점유 프로세스 찾기
lsof -i :3000

# Windows
netstat -ano | findstr :3000

해결: 점유 프로세스 종료 또는 MCP 서버 설정에서 다른 포트 지정.

사전 검사 (commit 전)

npm run preflight

포맷팅, 린트, 타입 오류 등 흔한 문제를 사전에 잡아냅니다.

디버그 모드

# CLI 디버깅
gemini --debug             # 상세 로깅 (-d)
# 인터랙티브 모드 중 F12 → 디버그 콘솔

# 환경 변수 (코어 디버그 상세도)
DEBUG_MODE=true gemini

# Node.js 디버거로 단계별 실행
node --inspect packages/cli/dist/index.js

종료 코드 (스크립팅용)

FAQ

자주 묻는 질문과 답변을 모았습니다.

일반

Q. Gemini CLI는 무료인가요?

네, Google 계정(OAuth)으로 로그인하면 Gemini Code Assist 기반의 무료 사용 할당량을 제공합니다. Gemini API 키(무료)의 경우 Flash 모델 위주로 제한된 RPM/일일 한도가 적용됩니다. 정확한 최신 한도는 공식 요금 페이지에서 확인하세요.

Q. 어떤 운영체제를 지원하나요?

macOS 15+, Windows 11 24H2+, Ubuntu 20.04+를 공식 지원합니다.

Q. 오프라인에서 사용할 수 있나요?

아니요, Gemini CLI는 Google의 AI 모델에 접근하기 위해 인터넷 연결이 필요합니다.

Q. Claude Code나 GitHub Copilot과 차이점은 무엇인가요?

Gemini CLI는 Google 계정만으로 무료 사용이 가능하며, Gemini 모델을 기반으로 합니다. 오픈소스이며 MCP 프로토콜 지원, 에이전트 스킬, 훅 등 확장성이 뛰어납니다.

Q. VS Code 등 IDE에서도 사용할 수 있나요?

Gemini CLI는 터미널 도구이므로 IDE 내 터미널에서 실행할 수 있습니다. ACP(Agent Client Protocol) 모드를 통해 프로그래밍 방식으로 IDE 확장과 연동도 가능합니다.

Q. 프로젝트에 따라 다른 설정을 사용할 수 있나요?

네, 프로젝트 루트의 GEMINI.md 파일과 .gemini/settings.json에 프로젝트별 설정을 작성하면 해당 폴더에서만 적용됩니다.

모델

Q. Gemini 3은 무엇인가요?

Gemini 3은 Google의 최신 AI 모델 시리즈입니다. Gemini CLI에서 프리뷰로 사용할 수 있으며, auto 모드에서 자동으로 선택될 수 있습니다.

Q. 서브 에이전트의 모델을 변경할 수 있나요?

현재 /model 명령어와 --model 플래그는 서브 에이전트에 영향을 주지 않습니다.

Q. Flash와 Pro 모델의 차이는 무엇인가요?

Flash는 빠르고 가벼운 작업(코드 설명, 간단한 Q&A)에 적합하고 Pro는 복잡한 추론, 대규모 코드 분석에 강합니다. Auto 모드에서는 프롬프트 복잡도에 따라 자동으로 선택됩니다.

Q. 컨텍스트 윈도우는 얼마나 되나요?

Gemini 2.5 Pro는 최대 100만 토큰(1M), Flash는 최대 100만 토큰의 컨텍스트 윈도우를 지원합니다. Gemini 3 계열 모델도 프리뷰로 제공 중이며 대규모 코드베이스도 한 번에 처리할 수 있습니다. 최신 수치는 공식 Gemini 3 페이지를 확인하세요.

MCP & 도구

Q. MCP 서버란 무엇인가요?

MCP(Model Context Protocol)는 AI 모델이 외부 도구와 통신하는 표준 프로토콜입니다. 파일 시스템, 데이터베이스, API 등 다양한 도구를 Gemini CLI에 연결할 수 있습니다.

Q. Python으로 MCP 서버를 만들려면 무엇이 필요한가요?

Python 3.10+, uv(패키지 매니저), mcp 패키지가 필요합니다. uvx mcp-server-filesystem처럼 별도 설치 없이 uvx로 바로 실행할 수도 있습니다.

Q. 에이전트 스킬과 MCP 서버의 차이는 무엇인가요?

MCP 서버는 독립적인 프로세스로 외부 도구를 제공하고, 에이전트 스킬은 SKILL.md 파일로 정의되며 .gemini/skills/ 또는 ~/.gemini/skills/ 경로에 위치합니다. 온디맨드로 작동하며 모델이 작업 관련성에 따라 자율적으로 활성화를 결정합니다.

보안

Q. 내 코드가 학습에 사용되나요?

인증 방법과 서비스 약관에 따라 다릅니다. 자세한 내용은 공식 문서의 약관 및 개인정보 보호 페이지를 확인하세요.

Q. 샌드박스 모드는 어떻게 작동하나요?

플랫폼별 격리 기술을 사용합니다. macOS는 Seatbelt, Linux는 Docker/gVisor, Windows는 icacls를 활용합니다. gemini -s로 활성화할 수 있습니다.

Q. 훅(Hook)을 사용해 AI 행동을 제어할 수 있나요?

네, BeforeTool, AfterTool, SessionStart, SessionEnd 등의 훅 이벤트에 쉘 스크립트를 연결하면 Gemini CLI가 특정 도구를 실행하기 전/후에 승인 요청, 로깅, 차단 등을 할 수 있습니다.

Q. API 키 없이 사용할 수 있나요?

네, Google 계정으로 OAuth 로그인하면 API 키 없이 사용할 수 있습니다. API 키는 자동화, CI/CD, 헤드리스 환경에서 유용합니다.