Gemini CLI Wrapper (gcw)

Read this in other languages: English, 한국어

Gemini CLI를 브라우저 및 모바일 환경에서 편리하게 사용할 수 있도록 도와주는 Tmux 기반 웹 인터페이스(WebUI) 래퍼입니다. 터미널의 강력함과 웹의 편의성을 결합하여 어디서든 중단 없는 개발 환경을 제공합니다.

✨ 주요 기능

• 지속성 있는 세션: Tmux를 기반으로 동작하여 브라우저를 닫거나 네트워크가 끊겨도 작업 중인 컨텍스트가 그대로 유지됩니다.
• 이미지 업로드 & 자동 참조: 클립보드의 이미지를 웹 UI에 붙여넣기만 하면 자동으로 서버에 업로드되고, 터미널에 @path/to/image 형태로 경로가 즉시 삽입됩니다.
• 강력한 파일 뷰어: 텍스트, 마크다운(분할 뷰 및 동기식 스크롤), 이미지 파일을 실시간으로 확인할 수 있는 전용 뷰어를 제공합니다.
• 모바일 지원: 텔레그램 bot을 연결해서 워크스페이스를 동시에 액세스할 수 있게 하였습니다.
• AI 에이전트 프랙티스: .agent/ 디렉토리를 통해 AI 에이전트와 협업할 때 유용한 규칙(Rules)과 모범 사례를 공유합니다.

데모 화면 및 영상

음성을 이용한 프롬프트 입력

2026.05.Gemini.CLI.wrapper.voice.prompt.demo.-.09.-.AI.mp4

• 나머지 영상
  • https://youtu.be/OrB4tIcn-Do - 리팩토링 규칙논의
  • https://youtu.be/z5kELIYIj30 - 리팩토링 도구 논의
  • https://youtu.be/n-GWdYEBBn8 - 추가 리팩토링 대상 결정
  • https://youtu.be/VO51VLH2MLc - 보조 세션을 통한 시스템 모니터링 및 코드 리뷰
  • https://youtu.be/8tw2Gujq5WE - 하네스 규칙을 피드백으로 추가
  • https://youtu.be/AxD_h1U9Eao - 보조 세션에게 새로운 기능에 대한 작업 계획서 작성 지시
  • https://youtu.be/HiByyLv-6-o - 나머지 리팩토링 작업
  • https://youtu.be/lQstH5bhzes - AI 의견 개진 방식을 하네스 엔지니어링 피드백에 반영

🚀 시작하기

1. 선행 조건 (Prerequisites)

이 프로젝트를 실행하기 위해 다음 도구들이 설치되어 있어야 합니다.

• Node.js (v18 이상 권장)
• Tmux (터미널 세션 관리)
• Gemini CLI (npm install -g @google/gemini-cli)

2. 설치 (Installation)

node module 설치 과정에 빌드 도구가 필요하여

sudo apt-get update && sudo apt-get install -y build-essential

tmux 설치

sudo apt-get install tmux

git clone https://github.com/your-username/public-gemini-cli-wrapper.git
cd public-gemini-cli-wrapper
npm install

3. Tmux 환경 설정 (One-time Setup)

웹 UI와 Tmux 간의 원활한 연동(클립보드, 색상 등)을 위해 다음 스크립트를 실행하여 설정을 최적화합니다. (기존 ~/.tmux.conf는 백업됩니다.)

./setup-tmux.sh

4. 서버 실행 (Run)

# 기본 5001 포트로 실행
./run.sh

5. 브라우저 접속

5001 포트가 외부에 열려 있거나 로컬에 브라우저가 있으면 그것을 사용하면 되지만, 원격에서 브라우저가 없는 호스트가 접속하는 경우에는 ssh 포트포워딩이 필요합니다.

ssh -L 35001:127.0.0.1:5001 <hostname>

그리고 나서 ssh를 접속한 클라리언트에서 http://localhost:35001로 접속합니다. (포트번호는 각자 클라이언트 환경에 맞게 변경)

🐳 Docker Support (Alternative)

Windows와 같이 Tmux 환경을 직접 구축하기 어려운 경우 Docker를 사용하여 실행할 수 있습니다. 자세한 내용은 **Docker Guide**를 참고하세요.

이제 브라우저에서 http://localhost:5001에 접속하여 Gemini CLI를 웹에서 바로 사용해 보세요!

---

📂 프로젝트 구조

• src/: 세션 관리 및 API 서버 로직 (Node.js)
• public/: 웹 UI 자산 (JS Core, Svelte 컴포넌트, CSS)
• docs/: 상세 사용자 가이드 및 도움말
• .agent/: AI 에이전트 협업을 위한 핵심 강령 및 프로젝트 규칙

🤝 기여하기 (Contributing)

이 프로젝트는 실험적인 기능을 다수 포함하고 있습니다. 버그 제보나 기능 제안은 Issue 또는 Pull Request를 통해 언제든 환영합니다.

📄 라이선스 (License)

MIT License