<div align="center">
<a href="https://github.com/foresturquhart/grimoire">
<img src="https://raw.githubusercontent.com/foresturquhart/grimoire/HEAD/.github/grimoire.png" alt="Grimoire" width="500" height="auto" />
</a>
</div>
<hr />
go
license
release
Grimoire는 디렉터리 내용을 Claude, ChatGPT, Gemini, DeepSeek, Llama, Grok 등과 같은 대규모 언어 모델(LLMs)이 해석하기에 최적화된 구조화된 출력 형식으로 변환하는 커맨드라인 도구입니다. 가볍고, 설정이 용이하며, 사용하기 편리합니다.
빠른 시작 (Quick Start)
Grimoire 설치 (Install Grimoire)
가장 빠르게 시작하는 방법은 다음 한 줄 설치 스크립트를 사용하는 것입니다:
curl -sSL https://raw.githubusercontent.com/foresturquhart/grimoire/main/install.sh | bash
이 스크립트는 사용자의 OS와 아키텍처를 자동으로 감지하고, 적절한 바이너리를 다운로드하여 PATH에 설치합니다.
기본 사용법 (Basic Usage)
기능 (Features)
- 다중 출력 형식 (Multiple Output Formats): 필요에 따라 Markdown, XML 또는 일반 텍스트 형식으로 출력을 생성합니다.
- 재귀적 파일 스캔 (Recursive File Scanning): 사용자 정의 가능한 확장자를 기반으로 적격 파일을 식별하기 위해 디렉터리 및 하위 디렉터리를 자동으로 탐색합니다.
- 콘텐츠 필터링 (Content Filtering): 무시할 디렉터리, 임시 파일 및 구성에 정의된 패턴을 건너뜁니다.
- 디렉터리 트리 시각화 (Directory Tree Visualization): 출력 시작 부분에 선택적 디렉터리 구조 표현을 포함합니다.
- Git 통합 (Git Integration): Git 저장소 내에서 작업할 때 커밋 빈도에 따라 파일을 우선순위 지정합니다.
- 비밀 감지 (Secret Detection): 실수로 노출되는 것을 방지하기 위해 파일에서 잠재적인 비밀 또는 민감한 정보를 스캔합니다.
- 비밀 마스킹/제거 (Secret Redaction): 전체 코드 구조를 유지하면서 감지된 비밀을 출력에서 선택적으로 마스킹(redact)합니다.
- 토큰 계산 (Token Counting): 생성된 출력의 토큰 수를 계산하여 LLM 컨텍스트 제한 관리에 도움을 줍니다.
- 최소화 파일 감지 (Minified File Detection): 높은 토큰 사용량에 대해 경고하기 위해 최소화된 JavaScript 및 CSS 파일을 자동으로 식별합니다.
- 유연한 출력 (Flexible Output): stdout 또는 지정된 파일로 출력을 지원합니다.
설치 (Installation)
전제 조건 (Prerequisites)
- Git (Git 기반 정렬을 사용하는 저장소에 필수).
가장 빠른 방법: 원라인 설치 스크립트 (Quickest: One-line Installation Script)
Grimoire를 설치하는 가장 쉬운 방법은 자동 설치 스크립트를 사용하는 것입니다:
curl -sSL https://raw.githubusercontent.com/foresturquhart/grimoire/main/install.sh | bash
이 스크립트는 다음을 자동으로 수행합니다:
- 운영 체제 및 아키텍처를 감지합니다.
- 시스템에 적합한 바이너리를 다운로드합니다.
/usr/local/bin (또는 sudo 접근 권한이 없는 경우 ~/.local/bin)에 설치합니다.- 바이너리를 실행 가능하게 만듭니다.
대안: 사전 컴파일된 바이너리 다운로드 (Alternative: Download Pre-compiled Binary)
릴리스 페이지에서 수동으로 사전 컴파일된 바이너리를 다운로드할 수도 있습니다.
- releases 페이지를 방문합니다.
- 시스템에 맞는 아카이브(예:
grimoire-1.2.2-linux-amd64.tar.gz 또는 grimoire-1.2.2-darwin-arm64.tar.gz)를 다운로드합니다.
- 아카이브를 압축 해제하여
grimoire 실행 파일을 가져옵니다.
grimoire 실행 파일을 시스템의 PATH에 있는 디렉토리로 이동시킵니다(예: /usr/local/bin 또는 ~/.local/bin). 시스템 전체 위치에는 sudo를 사용해야 할 수 있습니다:
tar -xzf grimoire-1.2.2-linux-amd64.tar.gz
cd grimoire-1.2.2-linux-amd64
sudo mv grimoire /usr/local/bin/
- 설치를 확인합니다:
go install을 사용한 설치
Go가 설치된 사용자에게는 go install이 간단한 설치 방법을 제공합니다:
go install github.com/foresturquhart/grimoire/cmd/grimoire@latest
소스에서 빌드하기
Grimoire를 소스에서 빌드하는 방법(개발 또는 사용자 정의에 유용함):
- 리포지토리를 클론합니다:
git clone https://github.com/foresturquhart/grimoire.git
cd grimoire
- 바이너리를 빌드합니다:
go build -o grimoire ./cmd/grimoire
- 바이너리를
PATH로 이동시킵니다:
mv grimoire /usr/local/bin/
- 설치를 확인합니다:
사용법
기본 명령어
grimoire [options] <대상 디렉토리>
옵션
-o, --output <경로>: 출력 파일을 지정합니다. 생략하면 표준 출력(stdout)을 기본값으로 합니다.
-f, --force: 이미 존재하는 경우 출력 파일을 덮어씁니다.
--format <형식>: 출력 형식을 지정합니다. 옵션은 md (또는 markdown), xml, 그리고 txt (또는 text, plain, plaintext)입니다. 기본값은 md입니다.
--no-tree: 출력 시작 부분의 디렉터리 트리 시각화를 비활성화합니다.
--no-sort: Git 커밋 빈도에 따른 파일 정렬을 비활성화합니다.
--ignore-secrets: 비밀 정보(secrets)가 감지되어도 출력 생성을 계속 진행합니다.
--redact-secrets: 감지된 비밀 정보를 실패 처리하는 대신 출력에서 마스킹(redact)합니다.
--skip-token-count: 출력 토큰 개수 계산을 건너뜁니다.
--version: 현재 버전을 표시합니다.
사용 예시 (Examples)
- 디렉터리를 Markdown으로 변환하고 출력을 표준 출력(stdout)에 인쇄합니다:
grimoire ./myproject
2. 출력을 파일로 저장합니다:
```bashbash
grimoire -o output.md ./myproject
- 기존 파일을 덮어씁니다:
grimoire -o output.md -f ./myproject
4. 디렉터리 트리가 없는 XML 출력을 생성합니다:
```bashbash
grimoire --format xml --no-tree -o output.xml ./myproject
- Git 기반 정렬이 없는 일반 텍스트(plain text) 출력을 생성합니다:
grimoire --format txt --no-sort -o output.txt ./myproject
6. 비밀 정보를 스캔하고 출력에서 마스킹합니다:
```bashbash
grimoire --redact-secrets -o output.md ./myproject
설정 (Configuration)
허용 파일 확장자 (Allowed File Extensions)
Grimoire는 특정 확장자를 가진 파일을 처리합니다. 이들은 코드베이스의 DefaultAllowedFileExtensions 상수를 수정하여 사용자 정의할 수 있습니다.
무시 경로 패턴 (Ignored Path Patterns)
DefaultIgnoredPathPatterns 상수에서 패턴과 일치하는 파일 및 디렉터리는 처리에서 제외됩니다. 여기에는 임시 파일, 빌드 아티팩트, 버전 관리 디렉터리가 포함됩니다.
사용자 정의 무시 파일 (Custom Ignore Files)
Grimoire는 추가적인 제외 패턴을 지정하기 위해 두 가지 유형의 무시 파일을 지원합니다:
.gitignore: 대상 디렉터리에 존재할 경우 표준 Git ignore 파일을 인식합니다..grimoireignore: Git ignore 파일과 동일한 구문을 따르는 Grimoire 전용 무시(ignore) 파일입니다.
이러한 파일들은 디렉터리별로 추가적인 무시 규칙을 지정할 수 있게 하여, 변환 과정에서 어떤 파일과 디렉터리를 생략해야 하는지에 대한 세밀한 제어(fine-grained control)를 제공합니다.
대용량 파일 처리 (Large File Handling)
Grimoire는 기본적으로 1MB보다 큰 파일을 처리할 때 경고 메시지를 표시합니다. 이러한 파일들은 여전히 출력에 포함되지만, 출력을 LLM에 공급할 때 발생할 수 있는 잠재적인 성능 영향에 대해 알려주는 경고가 기록됩니다.
난독화된 파일 감지 (Minified File Detection)
Grimoire는 여러 휴리스틱(heuristics)을 사용하여 난독화된 JavaScript 및 CSS 파일을 자동으로 감지합니다:
- 과도한 줄 길이
- 라인 대 문자 비율이 낮음
- 난독화된 파일에서 흔히 볼 수 있는 코딩 패턴의 존재
난독화된 파일이 감지되면, Grimoire는 경고를 기록하는데, 이는 이러한 파일들이 LLM에게 제한적인 가치를 제공하면서도 많은 토큰을 소모할 수 있기 때문입니다.
Grimoire는 세 가지 출력 형식을 지원합니다:
- Markdown (md) - 파일 경로를 제목으로 사용하여 파일 내용을 코드 블록으로 감싸는 기본 형식입니다.
- XML (xml) - 파일 경로를 속성(attribute)으로 사용하여 콘텐츠를 XML 형식으로 구조화합니다.
- Plain Text (txt) - 구분선(separator lines)을 사용하여 파일 간의 구분을 명확히 합니다.
각 형식은 메타데이터, 요약 섹션, 선택적 디렉터리 트리, 그리고 모든 파일의 내용을 포함합니다.
토큰 계산 (Token Counting)
Grimoire는 LLM 컨텍스트 제한을 관리하는 데 도움을 주기 위해 내장된 토큰 카운팅 기능을 제공합니다. 토큰 수는 많은 LLM이 사용하는 것과 동일한 토크나이저를 사용하여 추정됩니다. --skip-token-count 플래그를 사용하면 토큰 계산을 완전히 비활성화할 수 있습니다.
비밀 정보 감지 (Secret Detection)
Grimoire는 gitleaks의 기능을 활용하여 내장된 비밀 정보 감지 기능을 포함하고 있으며, 생성된 출력을 LLM이나 다른 도구와 함께 사용할 때 민감한 정보를 실수로 공유하는 것을 방지하는 데 도움을 줍니다.
기본적으로 Grimoire는 다음과 같은 광범위한 잠재적 비밀 정보들을 스캔합니다:
- API 키 및 토큰 (AWS, GitHub, GitLab 등)
- 개인 키 (RSA, SSH, PGP 등)
- 인증 자격 증명
- 서비스별 토큰 (Stripe, Slack, Twilio 등)
비밀 정보 감지 동작은 다음 플래그를 사용하여 제어할 수 있습니다:
--ignore-secrets: 비밀 정보가 감지되더라도 출력 생성을 계속합니다 (경고 로그).--redact-secrets: 감지된 모든 비밀 정보를 자동으로 [REDACTED SECRET: 설명] 형식으로 마스킹(redacts)합니다.
만약 비밀 정보가 감지되었으나 위 플래그 중 어느 것도 지정되지 않으면, Grimoire는 작업을 중단하고 경고 메시지를 표시하여 민감한 정보의 우발적인 노출을 방지하는 데 도움을 줍니다.
기여 (Contributing)
기여를 환영합니다! 시작하려면 다음 단계를 따르세요:
- 저장소(repository)를 포크(fork)하세요.
- 기능 또는 수정 사항을 위한 새 브랜치를 만드세요:
git checkout -b feature/my-new-feature
3. 변경 사항을 커밋하세요:
```bash
git commit -m "Add my new feature"
- 해당 브랜치를 포크에 푸시(push)하세요:
git push origin feature/my-new-feature
5. 풀 리퀘스트(pull request)를 여세요.
## 라이선스 (License)
Grimoire는 [MIT License](LICENSE)에 따라 라이선스가 부여되었습니다.
## 감사의 말 (Acknowledgements)
Grimoire는 다음 라이브러리들을 사용합니다:
- 구조화된 로깅을 위해 [zerolog](https://github.com/rs/zerolog).
- 비밀 정보 탐지 및 스캔을 위해 [gitleaks](https://github.com/zricethezav/gitleaks).
- 무시 패턴(ignore patterns) 처리를 위해 [go-gitignore](https://github.com/sabhiram/go-gitignore).
- 명령줄 인터페이스(command-line interface)를 위해 [urfave/cli](https://github.com/urfave/cli).
- 토큰 카운팅을 위해 [tiktoken-go](https://github.com/tiktoken-go/tokenizer).
## 피드백 및 지원 (Feedback and Support)
문제, 제안 또는 피드백이 있다면 [GitHub 저장소](https://github.com/foresturquhart/grimoire/issues)에서 이슈를 열어주세요.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
