새로운 라이브러리를 도입하기 전 성능을 평가하거나, 오픈소스의 정교한 구현 방식을 이해하고 싶을 때가 있습니다. 하지만 매번 저장소를 클론하고, 어디서부터 읽어야 할지 헤매는 일은 매우 번거롭습니다.

Repomix는 GitHub 저장소를 원격에서 즉시 AI용 파일로 변환해 줍니다. 내 컴퓨터에 코드를 펼쳐 놓지 않고도, 필요한 컨텍스트만 빠르게 얻어낼 수 있는 가장 효율적인 방법입니다.

클론 없이 바로 묶는다

별도의 git clone 과정 없이 명령어 한 줄로 가능합니다.

# 1. 전체 URL 지정
repomix --remote https://github.com/user/repo

# 2. 단축 표기 (권장)
repomix --remote user/repo

# 3. --remote 생략 (자동 인식)
repomix yamadashy/repomix

--remote 옵션은 GitHub 저장소를 대상으로 합니다. 특정 브랜치나 태그, 커밋 해시를 지정해 특정 시점의 코드를 묶을 수도 있습니다. 단, 원격 처리와 워치 모드는 함께 사용할 수 없습니다. 워치 모드는 오직 로컬 디렉터리의 변경 사항을 감시할 때만 동작합니다.

단축 표기는 어떻게 판정되는가

owner/repo 형태의 단축 표기는 로컬의 상대 경로와 모양이 같습니다. Repomix는 다음 규칙에 따라 이를 판정합니다.

판정 상황	처리 결과
같은 이름의 로컬 파일/폴더가 존재할 때	로컬 경로로 처리 (로컬 우선순위)
로컬에 없고 GitHub에서 접근 가능할 때	원격 저장소로 처리
패턴은 맞지만 접근 불가할 때 (비공개, 오타 등)	로컬 경로로 다시 시도 (폴백)
강제로 로컬 경로로 인식시키고 싶을 때	./ 접두사 사용 $\rightarrow$ repomix ./owner/repo

가장 흔한 실수는 로컬에 우연히 같은 이름의 폴더가 있을 때 발생합니다. 원격 저장소를 묶으려 했는데 로컬 폴더가 묶였다면, 폴더 이름을 확인하거나 ./ 접두사를 사용하세요.

브랜치·태그·커밋 고정하기

기본적으로는 저장소의 기본 브랜치(Default Branch)를 사용하지만, 특정 리비전을 지정해 정밀하게 분석할 수 있습니다.

# 특정 브랜치 지정
repomix --remote user/repo --remote-branch main

# 특정 태그(버전) 지정
repomix --remote user/repo --remote-branch v1.0.0

# 특정 커밋 해시 지정
repomix --remote user/repo --remote-branch 935b695

URL을 통해 직접 지정하는 것도 가능합니다.

repomix --remote https://github.com/user/repo/tree/main
repomix --remote https://github.com/user/repo/commit/836abcd7335137228ad77feb28655d85712680f1

팁: 리뷰나 보안 감사 결과를 문서화하는 작업이라면, 반드시 커밋 해시로 리비전을 고정하세요. 기본 브랜치는 계속 변경되므로, 어제 만든 결과물과 오늘의 결과물이 달라질 수 있습니다.

요구 조건과 출력 제어

원격 저장소를 처리하려면 다음 조건이 충족되어야 합니다.

• 시스템에 Git이 설치되어 있을 것
• 인터넷 연결 상태일 것
• 해당 저장소에 대한 읽기 권한이 있을 것

출력 제어는 로컬 실행과 동일합니다. -o로 파일명을 정하거나, --style로 포맷을 바꾸고, --compress로 토큰을 아낄 수 있습니다.

repomix --remote user/repo -o remote-analysis.xml --compress

Docker로 원격 저장소 묶기

호스트 환경을 깨끗하게 유지하고 싶다면 Docker 이미지를 사용하세요. (ghcr.io/yamadashy/repomix)

# 결과물을 현재 디렉터리에 저장
docker run -v .:/app -it --rm ghcr.io/yamadashy/repomix --remote user/repo

# 결과물을 별도의 ./output 폴더에 저장 (권장)
docker run -v ./output:/app -it --rm ghcr.io/yamadashy/repomix --remote user/repo

주의: 컨테이너 내부의 /app 경로가 호스트의 볼륨과 연결됩니다. 원격 저장소를 처리할 때 생성되는 임시 파일들과 결과물이 섞일 수 있으므로, ./output처럼 전용 폴더를 마운트하는 것이 깔끔합니다.

🛑 보안 경고: 원격 저장소 설정 파일은 미신뢰가 기본

가장 중요한 안전장치입니다. --remote로 가져온 저장소 안에 repomix.config.* 파일이 있더라도, Repomix는 이를 절대로 자동으로 로드하지 않습니다. 오직 사용자의 전역 설정과 명령줄 옵션만 적용됩니다.

이유는 설정 파일이 "데이터"가 아니라 "실행 가능한 코드"이기 때문입니다..ts나 .js 설정 파일은 읽는 순간 실행되며, input.processors는 임의의 셸 명령을 실행할 수 있습니다. 또한 잘못된 경로 설정을 통해 저장소 밖의 파일을 읽게 유도할 수도 있습니다. 낯선 저장소의 설정을 검토 없이 실행하는 것은 보안상 매우 위험한 행위입니다.

그럼에도 불구하고 해당 저장소의 설정을 신뢰하고 적용해야 한다면, 명시적으로 플래그를 켜야 합니다.

# 플래그 사용
repomix --remote user/repo --remote-trust-config

# 환경 변수 사용
REPOMIX_REMOTE_TRUST_CONFIG=true repomix --remote user/repo

인터랙티브 터미널에서는 설정을 로드하기 전 내용을 화면에 띄우고 확인을 요구합니다. [한 번만 신뢰 / 이 저장소는 다시 묻지 않음 / 중단] 중 하나를 선택할 수 있으며, 기본값은 중단입니다.

큰 저장소 처리와 트러블슈팅

저장소 규모가 너무 커서 처리가 안 된다면 다음 전략을 사용하세요.

• 대상 좁히기: --include로 필요한 폴더만 지정하세요.
• 토큰 절약: --remove-comments나 --compress를 활성화하세요.
• 접근 확인: 저장소가 공개 상태인지, Git 설치 여부와 네트워크 연결을 확인하세요.

특히 외부 라이브러리의 특정 모듈만 조사하고 싶을 때 유용한 조합입니다.

# 소스 코드와 문서만 빠르게 묶기
npx repomix --remote owner/repo --include "docs/**,src/**"

# 특정 확장자 파일만 골라 압축해서 묶기
npx repomix --remote owner/repo --include "**/*.ts" --compress

이렇게 생성한 파일을 AI에게 전달하면, 방대한 라이브러리 전체를 읽지 않고도 필요한 핵심 로직만 빠르게 분석할 수 있습니다. 다음 편에서는 개발 중 실시간으로 컨텍스트를 유지하는 워치 모드에 대해 알아보겠습니다.