Gemini-cli : Gemini CLI Companion

Gemini CLI Companion 은 vscode의 extension(확장 프로그램)으로
Gemini CLI와 vscode가 연동되게 해 줌.

 

Gemini CLI가
지금 VS Code에서
개발자가
현재 무엇을 보고 있는지
더 잘 이해하게 해 주는 extension임

---

요구조건

• VS Code 버전 1.99.0 이상
• Gemini CLI가 설치되어 있어야 함. (WSL의 vscode면 WSL의 해당 distro에 gemini-cli가 설치되어야함)
• Gemini CLI를 VS Code의 integrated terminal 안에서 실행되어야 함.

Linux 또는 macOS에서 GeminiCLI설치:
2025.12.26 - [개발환경] - Gemini CLI 설치 가이드 (Homebrew 이용)

Gemini CLI 설치 가이드 (Homebrew 이용)

Windows에서 Gemini CLI설치

https://blog.naver.com/dsaint31/224242974782

Install Gemini CLI for Windows

---

공식 참고 문서

https://geminicli.com/docs/ide-integration/#vs-code-companion-extension

IDE Integration

 

https://marketplace.visualstudio.com/items?itemName=Google.gemini-cli-vscode-ide-companion

Gemini CLI Companion - Visual Studio Marketplace

 

https://geminicli.com/docs/ide-integration/ide-companion-spec/

Gemini CLI companion plugin: Interface specification

---

주요 기능

다음과 같은 기능을 가짐.

Open Editor File Context

• Gemini CLI가 vscode의 에디터에서 현재 열어 둔 파일들을 인식하게 해줌.
• 이를 통해 프로젝트의 구조와 내용을 더 풍부하게 이해할 수 있음
  • Gemini CLI는 이를 통해 프로젝트 구조를 파악할 수 있음
  • 또한 현재 열어둔 여러 파일의 관계를 파악할 수 있고,
  • import 흐름, 함수 호출 흐름, 모듈 의존 관계를 파악하여 알려줄 수 있음.

지금 vscode의 에디터에서 보고 있는 파일(활성화된)과 최근 작업 파일들을 Gemini CLI가 자동으로 context로 참조가능함.

참고로 최근 작업 파일 10개(The 10 most recently accessed files in your workspace)까지 반영됨.

 

이를 통해 파일 내용을 전부 복붙하지 않아도,

Open Eidtor File Context를 바탕으로 Gemini CLI가 workspace context를 구축할 수 있음.

(이를 workspace awareness 라고도 부름)

주의할 점은
Gemini CLI의 workspace context에는
최근 접근 파일, 커서 위치, 선택 텍스트가 포함되나
전체 프로젝트를 다 파악하는 건 아님.

 

https://geminicli.com/docs/ide-integration/

IDE Integration

---

참고: workspace

작업의 기준이 되는 루트 디렉토리(root directory) — "내가 지금 작업하는 프로젝트 폴더"를 가리키는 개념.

---

참고: workspace context

Gemini CLI가 사용하는 "작업 중인 context(문맥)" 를 가리키는 용어.

 

즉, Gemini CLI Companion이 VS Code로부터 받아서 Gemini CLI에 넘겨주는 현재 작업 상황 정보 묶음임.

 

이 Gemini CLI Companion에서의 workspace context는 보통 다음 같은 것들을 의미:

• 현재 에디터에서 열려 있는 파일들 (정확하게는 최근 작업 중인 10개 파일임)
• 현재 활성 파일
• 커서가 놓인 위치
• 사용자가 선택한 텍스트 (16kB 제한)

Gemini CLI는 사용자가 프롬프트에 직접 쓴 문장 과 함께 workspace context를 바탕으로 대답을 하게 됨.
단, 프로젝트 전체를 미리 전부 인덱싱하진 않음.

---

Selection Context

• Gemini CLI가 에디터에서 커서 위치와 선택된 텍스트를 인식하고 접근 가능함.
• 이를 통해 현재 작업 중인 내용으로부터 직접 유용한 context를 얻을 수 있음.

이는 선택한 텍스트 자체를 Gemini CLI에 context로 전달함.

참고로 최대 16kB까지의 텍스트가 가능함.

 

다음의 경우에 유용.

• 함수 하나만 설명받고 싶을 때
• 특정 클래스만 리팩터링하고 싶을 때
• 긴 파일 전체가 아니라 일부 코드만 집중 분석하고 싶을 때

특히 active cursor position이 workspace context에 포함되므로

지금 사용자가 보고 있는 관심 지점을 Gemini CLI가 보다 잘 파악할 수 있음.

 

즉, 다음과 같은 프로프트가 가능:

현재 커서 위치 기준으로
이 함수가 어떤 역할을 하는지 설명해줘.
주변 함수와의 관계도 같이 알려줘.

---

Native Diffing

• Gemini CLI가 제안한 코드 변경 사항을
• vscode의 에디터 안에서 바로 확인하고, 수정하고, 적용할 수 있음.

사실 vscode 와 연동에서 가장 강력한 기능이라고 생각됨.

 

Gemini가 코드 수정안을 제안하면,

그 변경을 VS Code의 native diff viewer에서 직접 검토하고 수정하고 수락 또는 거절할 수 있음.

이를 통해 기존의 터미널보다 훨씬 쉽게 변경사항 등을 파악할 수 있음.

---

Launch Gemini CLI

• Command Palette(Cmd+Shift+P 또는 Ctrl+Shift+P)에서
• "Gemini CLI: Run" 명령을 통해 새 Gemini CLI 세션을 빠르게 시작할 수 있음.

---

튜토리얼

1. 설치

1. VS Code integrated terminal에서 Gemini CLI를 실행한 뒤 자동 연결 프롬프트가 나오면 허용
2. 이미 자동 프롬프트를 넘겼다면 Gemini CLI 안에서 /ide install 실행

공식 문서상 자동 감지가 되면 필요한 setup을 진행하고, 수동 설치 후에는 /ide enable을 실행할 것.

 

설치 이후 다음의 명령을 Gemini CLI에서 수행하여 활성화 시키거나 비활성화 시킬수 있음:

/ide enable
/ide disable

 

특히 설치가 다 끝났는데도 연동이 안되면 /ide enable 을 Gemini CLI 에서 입력해볼 것.

---

2. Gemini CLI 세션 시작하기

Cmd+Shift+P 또는 Ctrl+Shift+P를 눌러 Command Palette를 열고 Gemini CLI: Run을 실행

실습 절차

1. Command Palette 를 open.
2. Gemini CLI: Run을 실행.
3. integrated terminal에 새 Gemini CLI 세션이 뜨는지 확인.

2개 이상의 세션을 띄울 순 있으나 하나면 보통 충분함.

 

---

3. 튜토리얼을 위한 간단 프로젝트 만들기

다음과 같은 구조를 가짐:

simple_project
├── ds_main.py
├── report.py
└── utils.py

 

ds_main.py

from report import print_ratio, average

def run():
    print_ratio(10, 0)
    print(average([1, 2, 3, 4]))

if __name__ == "__main__":
    run()

 

report.py

from utils import safe_divide

def print_ratio(a, b):
    result = safe_divide(a, b)
    print(f"ratio = {result}")

def average(values):
    total = 0
    for v in values:
        total += v
    return total / len(values)

 

utils.py

def safe_divide(a, b):
    return a / b

• 0으로 나누는 부분에 대한 처리를 억지로 안 한 것임.

---

Open Editor File Context 기능 실습

Gemini CLI가 에디터에서 현재 열려 있는 파일들과 최근 작업 파일들을 context로 참고하는 기능을 확인해 보기

 

• main.py, report.py, utils.py를 모두 vscode 에디터에서 열기.
• main.py를 활성화 .
• integrated terminal에서 Gemini CLI를 실행하거나 command palette에서  Gemini CLI: Run을 실행.

위 과정 이후 Gemini CLI에 다음 프롬프트를 입력:

현재 열려 있는 파일 기준으로
이 프로젝트의 구조를 설명해줘.
각 파일의 역할, import 흐름, 함수 호출 흐름을 같이 정리해줘.

 

 

이후 Gemini CLI는 프롬프트에 파일 내용을 전부 복붙하지 않았음에도 현재 열려 있는 파일들을 바탕으로 설명을 시도함.

결과는 다음과 같은 형태임(한글과 영어로 대답하도록 미리 설정한 상태임)

---

Selection Context 기능 실습

Selection Context는 사용자가 선택한 텍스트를 Gemini CLI가 직접 context로 받아서 활용하는 기능임.

현재 selected text는 workspace context의 일부이며 최대 16KB까지만 전달 가능함.

 

실습 1 - 함수 하나 설명받기

1. report.py를 에디터에서 열고 활성화.
2. average() 함수 전체를 드래그해서 선택.

위의 상태에서 Gemini CLI에 다음 프롬프트를 입력:

선택한 함수의 역할을 설명해줘.
입력, 출력, 예외 가능성, 개선 포인트를 같이 알려줘.

프롬프트를 입력받고 나서 생각중인 Gemini CLI

결과는 다음과 같음:

0으로 나눌 경우 문제 등을 제대로 파악해서 알려주고 있음.

---

실습 2 - 특정 함수만 리팩터링 요청

이번에는 같은 average() 함수를 선택한 상태에서 다음의 프롬프트를 입력:

선택한 함수만 대상으로
가독성을 높이는 방향으로 리팩터링 아이디어를 제안해줘.
동작은 바꾸지 말고 설명 위주로 답해줘.

---

실습 3 - Cursor Position 실습

 

• report.py에서 print_ratio() 함수 내부 줄에 커서를 위치시킴.
• 단, 선택은 하지 않음.

다음 프롬프트를 입력해 볼 것:

현재 커서 위치 기준으로
이 함수가 어떤 역할을 하는지 설명해줘.
주변 함수와의 관계도 같이 알려줘.

 

다음의 프롬프트도 입력해볼 것:

현재 커서 근처 로직에서
버그 가능성이 있는 부분을 찾아줘.

---

Native Diffing 실습

이 기능이 VS Code 연동에서 가장 눈에 띄는 기능으로 Gemini CLI 가 코드 수정안을 제안하면 그 변경을 VS Code의 native diff viewer에서 직접 보고, 수정하고, accept 또는 reject할 수 있게 해 줌.

 

safe_divide()가 0으로 나누는 경우를 처리하도록 수정안을 받아 보고, diff editor에서 검토한 뒤 반영 또는 거절해보기 위해 다음을 실행:

 

• utils.py와 main.py를 vscode 에디터에 열어둔다.
• utils.py의 safe_divide() 함수에 커서를 위치시킬 것.

이후 다음 프롬프트를 입력:

현재 함수에서 0으로 나누는 경우를 안전하게 처리하도록 수정해줘.
변경안은 diff로 검토할 수 있게 해줘.

 

다음이 vscode의 native diff viewer를 보여줌:

• Gemini CLI: Accept Diff 는 native diff viewer의 오른족 상단에서 V 기호에 해당. (클릭시 변경이 이루어짐)
• Gemini CLI: Close Diff Editor 는 그 옆의 X 기호에 해당.

변경사항을 승인하는 건 Gemini CLI에서 1번을 선택해서 엔터를 눌러도 됨.

 

승인하고 추가적으로 이번에는 report.py의 average() 함수만 선택한 뒤 다음처럼 요청해 볼 것:

선택한 함수만 대상으로
빈 리스트가 들어오는 경우를 안전하게 처리하도록 수정해줘.
diff로 보여줘.

---

추천 사용 프롬프트

코드 이해

1. 관련 파일 2개에서 5개 정도만 vscode 에디터 탭에 open
2. 핵심 함수에 커서를 위치시킴
3. 필요하면 함수 일부를 선택할 수도 있음
4. Gemini CLI에 다음의 프롬프트로 설명을 요청

예시 프롬프트:

현재 열려 있는 파일과 커서 위치 기준으로
이 기능의 전체 흐름을 설명해줘.
import 관계와 호출 관계도 같이.

---

국소적인 코드 분석

1. 함수 하나만 선택.
2. 다음의 프롬프트로 선택한 부분만 설명 및 분석 요청

예시 프롬프트:

선택한 함수만 기준으로
입력, 출력, edge case, 개선 포인트를 분석해줘.

---

안전한 최소한 수정 처리

1. 수정 대상 함수에 커서를 위치시킴.
2. "최소 수정만" 요청.
3. diff viewer에서 검토.
4. 검토 후 Accept 또는 Close를 선택

예시 프롬프트:

현재 함수에서 버그만 최소 수정으로 고쳐줘.
스타일 변경은 하지 말고 diff로 보여줘.

---

같이 보면 좋은 자료들

2026.04.12 - [Python] - Namespace, Frame, and Context

Namespace, Frame, and Context

 

2026.04.12 - [개발환경] - Gemini-CLI: GEMINI.md - Local Instructional Context

Gemini-CLI: GEMINI.md - Local Instructional Context

 

2024.03.11 - [개발환경] - [vscode] 기초 사용법과 단축키

[vscode] 기초 사용법과 단축키

2025.12.26 - [개발환경] - Gemini CLI 설치 가이드 (Homebrew 이용)

Gemini CLI 설치 가이드 (Homebrew 이용)

---

2025.01.17 - [utils] - [summary] vscode

[summary] vscode