gemini-cli 딥다이브
— 터미널 안의 에이전트 루프, 정책 엔진, 확장 체계 읽기

1프로젝트 한줄 요약

gemini-cli는 터미널에서 gemini를 치면 뜨는 대화형 코딩 에이전트로, 모델 호출·도구 실행·권한 확인·확장 로딩을 한 프로그램에 묶어 둔 npm 패키지(@google/gemini-cli)입니다. 같은 엔진을 gemini -p "질문" 같은 비대화형 모드로도 쓸 수 있어 스크립트와 CI에 끼우기도 쉽습니다.

README가 내세우는 쓰임은 세 가지입니다. 큰 코드베이스를 질문·수정하기, 이미지나 PDF에서 앱 초안 만들기, PR 조회나 리베이스 같은 운영 작업 자동화입니다. MCP 서버를 붙이면 이미지·영상 생성 같은 외부 능력도 같은 대화에서 부릅니다.

1-1. 설치 방법과 첫 명령

# 설치 없이 실행
npx @google/gemini-cli

# 전역 설치 (README 기준: npm / Homebrew / MacPorts / conda 환경 안의 npm)
npm install -g @google/gemini-cli
brew install gemini-cli

# 대화형 시작, 비대화형 질의, 파이프 입력
gemini
gemini -p "summarize README.md"
cat logs.txt | gemini

릴리스 채널은 latest(매주 화요일 UTC 20:00 안정판), preview(화요일 UTC 23:59), nightly(매일 UTC 00:00)로 나뉘며 각각 npm install -g @google/gemini-cli@preview처럼 태그로 받습니다.

인증은 README가 세 가지를 안내합니다. Google 계정 로그인(OAuth), GEMINI_API_KEY, Vertex AI입니다. 조직 유료 라이선스는 GOOGLE_CLOUD_PROJECT 설정이 필요하다고 적혀 있습니다.

2왜 주목받는가

트렌딩 이유를 저장소가 직접 말해 주지는 않으므로, 소스에서 확인되는 특징을 근거로 세 가지를 짚습니다. 순위 자체는 TrendShift 모멘텀 점수일 뿐 품질 평가가 아닙니다.

2-1. 확인되는 강점

2-2. 같은 종류의 도구와 나란히 보기

이 사이트에는 같은 분류의 openai/codex, anthropics/claude-code, opencode 딥다이브도 있습니다. 공통 골격(에이전트 루프, 도구, 권한, 컨텍스트 파일)은 같고, 다른 점은 기본 모델 계열과 컨텍스트 파일 이름(GEMINI.md)입니다. 세부 기능 우열은 각 저장소가 빠르게 바뀌므로 이 문서에서는 판정하지 않습니다.

3기술 스택 전체 지도

추적 파일 약 3,036개 중 TypeScript(.ts) 1,774개, TSX(.tsx) 420개로 코드의 대부분이 TypeScript입니다. 나머지는 문서 168개(.md), 스냅샷 120개, 아이콘 98개(.svg) 등이고, 테스트 관련 파일이 1,300개 남짓이라 코드 못지않게 검증 자산이 큽니다(파일명에 test가 들어간 수 기준).

백엔드 서버는 없습니다. 모델 호출은 사용자 PC에서 Google API로 직접 나가며, 로그인 토큰과 API 키는 keychainService.ts, fileKeychain.ts, apiKeyCredentialStorage.ts 같은 파일이 저장·조회를 맡습니다(파일 이름으로 확인한 구조이고 저장 위치 세부는 읽지 않았습니다).

4아키텍처 심화 분석

루트 GEMINI.md는 구조를 이렇게 설명합니다. packages/cli는 사용자와 맞닿는 터미널 UI·입력 처리, packages/core는 Gemini API 호출·프롬프트 조립·도구 실행을 맡습니다. 나머지 패키지(a2a-server, sdk, devtools, vscode-ide-companion, test-utils)는 이 두뇌를 다른 방식으로 쓰기 위한 껍데기입니다.

4-1. 한 턴이 지나가는 길

client.ts의 GeminiClient.sendMessageStream()은 비동기 제너레이터입니다. 호출되면 먼저 루프 감지기를 리셋하고, 훅이 켜져 있으면 BeforeAgent 훅을 실행합니다. 훅이 실행을 멈추거나 막을 수 있고, 추가 문맥을 <hook_context> 태그로 요청에 덧붙일 수도 있습니다. 그 뒤 processTurn()이 컨텍스트 압축(tryCompressChat)을 시도하고 Turn.run()으로 모델 응답을 스트리밍합니다.

스트림 이벤트는 core/turn.ts의 GeminiEventType으로 정의됩니다. 내용(content), 생각(thought), 도구 호출 요청, 압축 완료(chat_compressed), 루프 감지(loop_detected), 재시도(retry), 컨텍스트 창 초과 예고(context_window_will_overflow) 등 18개 안팎입니다. UI는 이 이벤트를 받아 그릴 뿐이라 같은 두뇌를 다른 화면에 붙이기 쉽습니다.

4-2. 도구 호출 — 스케줄러와 정책 엔진

모델이 도구 호출을 요청하면 scheduler/scheduler.ts(1,018줄)의 Scheduler 클래스가 큐로 받아 처리합니다. _processNextItem 안의 순서가 이 저장소에서 가장 읽을 가치가 큰 부분입니다.

1. 훅(BeforeTool)이 인자를 고쳐 쓸 수 있습니다. 고쳐졌다면 호출 객체의 인자와 invocation이 교체됩니다.
2. checkPolicy()가 정책 엔진에서 ALLOW / ASK_USER / DENY 중 하나를 얻습니다. 훅이 ask를 돌려주면 ASK_USER로 강제됩니다.
3. "오염 위험"(hasTaintedOrBuildFileRisk)이 감지된 호출은 ALLOW였어도 대화형이면 확인을 요구하고, 비대화형이면 아예 DENY로 바꿉니다.
4. DENY면 오류 응답을 만들어 모델에게 돌려주고, ASK_USER면 확인 루프에서 사용자 응답(ToolConfirmationOutcome)을 기다립니다.
5. 승인되면 실제 도구가 실행되고 결과가 다음 턴 입력으로 돌아갑니다.

# packages/core/src/policy/policies/write.toml 의 규칙 모양 (발췌)
[[rule]]
toolName = "replace"        # 파일 수정 도구
decision = "ask_user"       # 기본: 물어본다
priority = 10
interactive = true

[[rule]]
toolName = "replace"
decision = "allow"
priority = 15
modes = ["autoEdit"]        # auto-edit 모드에서는 허용

정책 파일 머리말 주석이 우선순위 규칙을 설명합니다. 높은 숫자가 이기고, 계층은 기본 < 확장 < 워크스페이스 < 사용자 < 관리자 순으로 정수부가 1~5로 나뉩니다(예: 기본 계층 우선순위 100은 1.100, 사용자 계층은 4.x). 그래서 조직 관리자가 정한 규칙을 개인 설정이 뒤집지 못합니다. 승인 모드는 ApprovalMode 열거형의 default, autoEdit, yolo, plan 네 가지이고, policies/ 폴더에는 read-only.toml, write.toml, plan.toml, yolo.toml, sandbox-default.toml 등이 모드별로 나뉘어 있습니다.

4-3. 모델 라우팅

core/src/routing/modelRouterService.ts는 전략 목록을 구성해 순서대로 시도합니다. 코드에서 확인되는 전략은 Fallback, Override, ApprovalMode, Default, Classifier, NumericalClassifier, GemmaClassifier이고, CompositeStrategy가 이를 묶습니다. 결과는 사용할 모델 문자열과 source, latencyMs, reasoning을 담은 메타데이터입니다. 쉬운 질문은 작은 모델, 어려운 계획은 큰 모델로 보내는 "Auto" 선택이 이 층에서 일어납니다(docs/cli/model-routing.md).

4-4. 확장 체계 5종

서브에이전트는 "메인 에이전트에게 도구 이름으로 노출"됩니다. agents/에는 codebase-investigator.ts, generalist-agent.ts, cli-help-agent.ts, 브라우저를 조작하는 browser/ 하위 폴더, 원격 에이전트(remote-invocation.ts, a2a-client-manager.ts) 구현이 보입니다. 서브에이전트는 자체 시스템 프롬프트와 독립된 컨텍스트 창을 가져 메인 대화의 토큰을 아낍니다(docs/core/subagents.md).

4-5. 안전장치

• 샌드박스: sandboxManagerFactory.ts가 OS별 구현을 고릅니다. macOS는 seatbelt 프로필(baseProfile.ts, seatbeltArgsBuilder.ts), Linux는 bubblewrap 인자 빌더, Windows는 C# 헬퍼가 있습니다. 컨테이너 방식은 --sandbox 플래그와 GEMINI_SANDBOX 환경변수로 켭니다(docs/cli/sandbox.md, 루트 Dockerfile).
• 폴더 신뢰: trustedFolders.ts와 --skip-trust 플래그가 낯선 폴더의 설정·훅 자동 실행을 막는 용도로 보입니다.
• 환경변수 정리: services/environmentSanitization.ts(자식 프로세스로 넘기는 환경에서 민감값을 거르는 것으로 읽히지만 세부 규칙은 확인하지 않음).
• 루프 감지: loopDetectionService.ts가 같은 호출을 반복하는 상황을 찾고, 이벤트 loop_detected로 UI에 알립니다.

5디렉토리 구조 해부

파일 수는 테스트 파일(*.test.ts)을 뺀 .ts/.tsx 기준으로 cli 558, core 466, a2a-server 21, sdk 11, devtools 5, vscode-ide-companion 6입니다. 테스트가 소스 옆에 나란히 있는 구조라 읽을 때 테스트 파일이 함수 사용 예시 역할을 합니다.

5-1. 읽는 순서 제안

6학습 포인트 (기술별)

에이전트 CLI에서 어려운 부분은 모델 호출이 아니라 "도구 실행 전에 누가 무엇을 허락하는가"이고, 이 저장소는 그 답을 정책 엔진·훅·샌드박스 세 겹으로 코드에 남겨 두었습니다.

7하드웨어 / 시스템 요구사항

docs/get-started/installation.mdx의 권장 사양을 옮깁니다.

소스를 직접 빌드하려면 npm install 뒤 npm run build, 실행은 npm run start입니다(GEMINI.md). 이 분석은 어떤 빌드나 테스트도 실행하지 않고 코드를 읽기만 했습니다.

8직접 해볼 수 있는 실습 과제

과제 1. 첫 비대화형 호출 입문

npx @google/gemini-cli -p "이 폴더의 파일 구조를 3줄로 요약해줘"
cat package.json | gemini -p "의존성 중 눈에 띄는 것 3개를 골라 이유를 설명해줘"

목표: 대화형 모드와 -p 모드의 차이를 체감하고, 파이프 입력이 프롬프트에 붙는 방식을 확인합니다.

과제 2. GEMINI.md로 행동 바꾸기 입문

연습용 저장소 루트에 GEMINI.md를 만들어 "답변은 한국어로, 변경 전 항상 계획을 먼저 말할 것" 같은 지침을 넣고 같은 질문을 지침 유무로 비교합니다. 로딩 순서(전역 → 워크스페이스 → JIT)는 docs/cli/gemini-md.md와 대조합니다.

과제 3. 승인 모드 비교 초급

gemini --approval-mode plan        # 읽기 전용 계획 모드
gemini --approval-mode auto_edit   # 파일 수정은 자동 승인
gemini --approval-mode default     # 수정마다 확인

같은 요청("README 오탈자 고쳐줘")을 세 모드로 실행해 확인 대화상자가 언제 뜨는지 기록합니다. 그다음 policies/write.toml, plan.toml의 규칙과 관찰 결과를 대조하세요. 연습은 반드시 버려도 되는 저장소에서 합니다.

과제 4. 훅으로 위험 명령 막기 중급

docs/hooks/writing-hooks.md를 따라 BeforeTool 훅 스크립트를 만들고, 셸 도구 호출 인자에 rm -rf가 있으면 차단하게 해 봅니다. 훅 이벤트 표(docs/hooks/index.md)와 scheduler.ts의 훅 처리 코드(인자 수정, ask 결정)를 함께 읽으면 어디에 끼어드는지 보입니다.

과제 5. 소스 추적 보고서 고급

코드를 실행하지 않고, 사용자가 "파일 하나 고쳐줘"라고 입력한 순간부터 replace 도구가 실행되기까지의 호출 경로를 gemini.tsx → client.ts → turn.ts → scheduler.ts → tools/edit.ts 순으로 따라가며 함수 이름과 줄 번호를 표로 정리합니다. 막히는 곳은 같은 이름의 *.test.ts가 호출 예시를 보여줍니다.

9관련 기술 심화 학습 로드맵

비교 학습으로 이 사이트의 openai/codex, anthropics/claude-code 딥다이브를 같은 질문("도구 실행 전 권한은 누가 정하나")으로 읽으면 설계 차이가 선명해집니다.

10핵심 키워드 사전

11참고 링크

• github.com/google-gemini/gemini-cli — 저장소
• geminicli.com/docs — 공식 문서(README에서 안내)
• ROADMAP.md — 로드맵 원칙
• GEMINI.md — 저장소 구조 요약
• npm: @google/gemini-cli
• Antigravity CLI 전환 안내 — README 공지가 가리키는 블로그