Codeglance는 모든 코드베이스에 대해 10초 만에 개요를 제공하는 CLI 도구입니다.
Overview
Codeglance는 저장소의 매니페스트 파일과 파일 구조를 읽어서 프레임워크, 실행 방법, 시작 지점 등 코드베이스에 대한 핵심 정보를 요약합니다. 설치나 설정이 필요 없으며, 단일 명령어로 실행됩니다. 새로운 코드베이스에 합류할 때, 의존성을 평가할 때, 오래된 프로젝트로 돌아올 때, 또는 LLM에 코드베이스 컨텍스트를 제공하기 전에 유용합니다.
Background
기존 도구들은 코드 라인 수를 세거나(tokei, scc), 전체 소스 코드를 LLM에 전달하는 데 집중했습니다(repomix, code2prompt). Codeglance는 프레임워크 감지, 실행 명령어, 시작 파일, CI/CD 등 개발자가 실제로 필요로 하는 ‘방향 정보’에 초점을 맞춘 오리엔테이션 레이어를 제공합니다.
How It Works
Codeglance는 주어진 디렉토리(기본값: 현재 디렉토리)의 매니페스트 파일을 읽습니다. 지원하는 생태계는 Node.js(package.json), Python(pyproject.toml, requirements.txt), Go(go.mod), Rust(Cargo.toml), C/C++(CMakeLists.txt)입니다. 각 생태계에 대해 감지된 프레임워크와 주요 패키지, 패키지 관리자, 실행/빌드/테스트 명령어, CI/CD 워크플로우, 컨테이너 설정 등을 추출하여 구조화된 출력을 생성합니다.
출력 형식
- 기본 모드: 터미널에 컬러 텍스트 출력
--for-ai: LLM에 붙여넣을 수 있는 간결한 컨텍스트 브리프(약 300토큰 미만)--markdown: 마크다운 파일로 저장 가능--json: 기계가 읽을 수 있는 JSON 출력
주요 특징
- 프레임워크 감지: 50개 이상의 Node.js 패키지, 10개 이상의 Python 프레임워크 등을 감지
- 실행 명령어 추천: 매니페스트의 스크립트 섹션을 기반으로 dev, build, test, lint 명령어 추출
- 시작 파일 제안: 파일 깊이, 이름 패턴, 크기를 기반으로 “먼저 읽어야 할 파일” 목록 제공
- 도구 감지: CI/CD(GitHub Actions 워크플로우 수), 컨테이너(Docker), 린터 등을 감지
- 언어 통계: 각 언어별 파일 수와 라인 수를 간단한 막대 차트로 표시
Key Ideas
- 오리엔테이션 레이어 — 코드 라인 수를 세거나 소스 코드를 덤프하는 대신, 저장소의 전체적인 맥락을 제공합니다.
- 제로 설치 —
npx codeglance로 즉시 실행 가능하며 전역 설치가 필요하지 않습니다. - 휴리스틱 기반 — 소스 코드 구문 분석 없이 매니페스트 파일과 파일 구조만 읽습니다. 따라서 표준 매니페스트가 없는 프로젝트에서는 출력이 얕을 수 있습니다.
- LLM 친화적 —
--for-ai모드를 통해 LLM에게 코드베이스 컨텍스트를 제공하기 위한 최적화된 출력을 생성합니다.
Examples / Use Cases
- 새 코드베이스 합류:
npx codeglance를 실행하면 10초 만에 저장소의 프레임워크, 실행 방법, 시작 파일을 파악할 수 있습니다. - 의존성 평가: 라이브러리를 채택하기 전에 해당 라이브러리가 실제로 사용하는 의존성과 도구를 확인할 수 있습니다.
- 온보딩 문서 생성:
codeglance --markdown --output docs/codebase-tour.md로 라이브 온보딩 문서를 생성할 수 있습니다. - LLM 컨텍스트 제공:
codeglance --for-ai출력을 Claude, GPT, Gemini에 붙여넣어 코드베이스 이해를 돕습니다.
Limitations / Considerations
- 휴리스틱, 의미론적 아님 — 소스 코드 로직을 이해하지 않고 매니페스트와 파일 구조만 읽습니다.
- 매니페스트 의존적 — 표준 패키지 파일이 없는 프로젝트는 얕은 출력만 제공합니다.
- 혼합 생태계 — Python 백엔드 + Node.js 프론트엔드처럼 여러 생태계가 섞인 저장소는 첫 번째 감지된 생태계 기준으로 분석됩니다.
- 프레임워크 자체 저장소 — FastAPI, Gin 등 프레임워크 자체가 저장소인 경우 자체 의존성만 표시되고 이름이 감지되지 않습니다.
- 지원되지 않는 언어 — Java, Ruby, PHP는 아직 지원되지 않지만 파일 수는 통계에 포함됩니다.
- 모노레포 — 단일 요약만 제공되며 패키지별 분석은 제공되지 않습니다.
- 대규모 저장소 — 25,000개 파일로 제한됩니다.
- 시작 파일 순위는 근사치 — 가져오기 그래프 분석이 아닌 파일 깊이, 이름 패턴, 크기 기반입니다.