Context Builder

병렬 처리 기반의 빠른 스캔

사용 가능한 CPU 코어를 모두 활용하여 수천 개의 파일을 수 초 내에 처리합니다. 디렉터리 순회는 병렬로 진행되며, .gitignore 패턴과 별도로 무거운 폴더(node_modules, dist, build, __pycache__, .venv, vendor 등)는 자동으로 제외됩니다.

관련성 기반 파일 정렬

설정 파일과 프로젝트 문서를 먼저 배치하고, 소스 코드는 진입점 우선, 테스트·문서·빌드/CI·락파일 순으로 정렬해 LLM이 프로젝트 구조를 빠르게 파악하도록 돕습니다.

컨텍스트 예산 관리

–max-tokens 옵션으로 출력 토큰 상한을 지정할 수 있고, 출력이 128K 토큰을 넘으면 알림과 함께 제안을 표시합니다. –token-count는 tiktoken-rs 기반의 실제 토큰 계산값을 제공합니다.

Tree-Sitter AST 분석 (선택 사항)

–signatures로 함수·클래스 시그니처만 추출하고, –structure로 구조 요약을 덧붙이며, –truncate smart 옵션으로 AST 경계 기준으로 잘라낼 수 있습니다. Rust, JavaScript, TypeScript, Python, Go, Java, C, C++를 지원합니다.

필터링·미리보기·라인 번호

-f/–filter로 확장자를 지정하거나 -i/–ignore로 폴더·파일명을 제외할 수 있고, –preview로 출력 없이 파일 트리만 확인할 수 있습니다. –line-numbers로 코드 블록에 줄 번호를 추가할 수 있습니다.

설정 파일과 자동 diff

context-builder.toml에 출력 경로, 필터, 무시 목록, 토크나이저 인코딩(o200k_base 기본, cl100k_base 선택) 등을 저장해 반복 실행을 일관되게 유지합니다. timestamped_output과 auto_diff를 함께 켜면 이전 스냅샷과의 per-file diff를 자동으로 생성하며, –diff-only로 변경 요약과 수정 파일의 diff만 출력해 토큰을 절약할 수 있습니다.

설치 및 기본 사용

Windows에서는 winget으로 한 줄 설치가 가능합니다. 명령 프롬프트에서 context-builder [옵션]을 실행하면 현재 디렉터리를 처리해 output.md를 생성하고, LLM 프롬프트에 그대로 붙여 넣어 사용할 수 있습니다.

• winget 설치: winget install --id igorls.context-builder --exact
• 기본 실행: context-builder (현재 디렉터리 → output.md)
• 대상 지정: context-builder -d /path/to/project -o documentation.md
• 확장자 필터: context-builder -f rs -f toml
• 토큰 상한: context-builder --max-tokens 100000
• 미리보기: context-builder --preview
• stdout 스트리밍: context-builder -o - | llm
• 설정 초기화: context-builder --init

PowerShell을 선호한다면 GitHub 릴리스의 context-builder-x86_64-pc-windows-msvc.zip을 받아 %LOCALAPPDATA%Programscontext-builder에 풀고 PATH에 추가해 사용할 수 있습니다. Linux/macOS는 install.sh를, 소스 빌드는 cargo install –path .를 통해 설치할 수 있습니다.

활용 예시

• 대규모 저장소를 LLM에 넣기 전 토큰 예산에 맞춰 잘라내고, 파일 정렬을 통해 모델이 먼저 핵심 설정과 진입점을 파악하도록 돕습니다.
• Rust 또는 TypeScript 프로젝트에서 –signatures와 –truncate smart를 함께 사용해 함수 시그니처 위주의 압축된 컨텍스트를 만들고 AST 경계에서 안전하게 자릅니다.
• CI 환경에서 timestamped_output과 auto_diff를 켜 두면 빌드 사이에 변경된 파일의 diff만 모아 검토용 문서를 자동으로 갱신할 수 있습니다.

제한 및 확인 사항

• Tree-Sitter 기반의 AST 분석(–signatures, –structure, –truncate smart, –visibility)은 지원 언어(Rust, JavaScript, TypeScript, Python, Go, Java, C, C++)에 한해 적용됩니다.
• –visibility 필터는 Rust, Go, Java, TypeScript에서만 동작하며 그 외 언어에서는 미적용 경고를 표시합니다.
• 매우 큰 코드베이스에서는 토큰 예산을 초과할 수 있으며, –max-tokens로 상한을 지정해 잘라내거나 제외해야 합니다.
• 라이선스는 MIT이며, 자세한 조건은 저장소의 LICENSE 파일에서 확인해야 합니다.