Molayo

© 2026 Molayo

GitHub요약2026. 05. 20. 16:20

mr-karan/hodor

요약

Hodor는 GitHub, GitLab, Gitea 등 다양한 플랫폼의 PR/MR 및 로컬 diff를 분석하는 에이전트 기반 코드 리뷰 도구입니다. pi-coding-agent SDK를 기반으로 작동하며, bash, grep, git diff 등의 도구를 사용하여 자율적으로 버그를 찾고 구조화된 리뷰를 제공합니다.

핵심 포인트

  • GitHub, GitLab, Gitea 및 로컬 Git 변경 사항을 지원하는 멀티 플랫폼 에이전트
  • stateful agent로서 도구를 활용해 자율적인 코드 분석 및 버그 탐지 수행
  • Anthropic, OpenAI 등 다양한 LLM 제공업체와 모델 지원
  • CI 환경을 위한 Docker 이미지 및 npx를 통한 간편한 실행 지원
  • 커밋되지 않은 변경 사항까지 검토 가능한 로컬 모드 제공

GitHub PRs, GitLab MRs, Gitea/Forgejo PRs 및 로컬 diff를 위한 에이전트 기반 코드 리뷰어 (Agentic code reviewer)입니다. pi-coding-agent SDK를 기반으로 작동합니다.

Hodor는 상태 유지 에이전트 (stateful agent)로서 도구(bash, grep, read, git diff)를 사용하여 코드 변경 사항을 자율적으로 분석하고, 버그를 찾아내며, 구조화된 리뷰를 게시합니다.

# 바로 실행 (설치 불필요, 항상 최신 버전)
npx @mrkaran/hodor <PR_URL>
# 또는 전역 설치
...

CI 환경을 위해 ghcr.io/mr-karan/hodor:latest에서 Docker 이미지도 사용할 수 있습니다.

# LLM 제공업체를 위한 API 키 설정
export ANTHROPIC_API_KEY=sk-... # Anthropic (기본값)
export OPENAI_API_KEY=sk-... # OpenAI
...

# GitHub PR 리뷰
npx @mrkaran/hodor https://github.com/owner/repo/pull/123
# GitLab MR 리뷰 (셀프 호스팅 포함)
...

npm install -g를 통해 전역으로 설치했다면, npx @mrkaran/hodor를 hodor로 대체하여 사용하세요.

PR URL 없이 로컬 git 변경 사항을 리뷰할 수 있습니다. 푸시 전 리뷰 (pre-push reviews), Bitbucket PR 또는 모든 git 저장소에 유용합니다.

# origin/main(기본값)을 기준으로 커밋되지 않은 변경 사항 리뷰
npx @mrkaran/hodor --local
# 특정 브랜치 또는 ref를 기준으로 리뷰
...

로컬 모드 (Local mode):

  • 커밋뿐만 아니라 커밋되지 않은 변경 사항 (uncommitted changes) (staged + unstaged)을 포함합니다.
  • **git 저장소 루트 (git repo root)**로 자동 해결됩니다 (하위 디렉토리에서도 작동).
  • PR 메타데이터 가져오기 및 워크스페이스 클로닝 (workspace cloning)을 건너뜁니다.
  • --post 옵션이 비활성화됩니다 (게시할 원격 저장소가 없음).
플래그 (Flag)기본값 (Default)설명 (Description)
--modelanthropic/claude-sonnet-4-5-20250929provider/model-id 형식의 LLM 모델. 권장 사항: Anthropic, OpenAI, Bedrock, OpenRouter. 기타 pi-ai 제공업체 (예: Mistral, Gemini, xAI, Groq)는 최선을 다해 지원(best-effort)합니다. docs/MODELS.md를 참조하세요.
--reasoning-effort–확장된 사고 (Extended thinking): low, medium, high
--ultrathinkOff최대 추론 노력 (Maximum reasoning effort)
--localOff로컬 Git 변경 사항 검토 (PR URL 불필요)
--diff-againstorigin/main--local 모드에서 비교 대상이 될 Git 참조 (ref)
--postOffPR/MR에 댓글로 리뷰 게시
--review-stylehybridGitLab 게시 스타일: summary, inline, 또는 hybrid
--code-quality–GitLab 코드 품질 보고서를 위한 CodeClimate JSON 아티팩트(artifact) 작성
--commit-statusOffGitLab MR 헤드 SHA에 통과/실패 커밋 상태 (commit status) 게시
--prompt–리뷰 프롬프트에 사용자 정의 지침 (custom instructions) 추가
--prompt-file–사용자 정의 프롬프트 파일 사용
--workspaceTemp dir워크스페이스 디렉토리 (더 빠른 다중 PR 리뷰를 위해 재사용 가능)
--bedrock-tags–AWS Bedrock을 위한 JSON 비용 할당 태그 (cost allocation tags)
--prometheus-push–리뷰 메트릭을 Prometheus Pushgateway 또는 VictoriaMetrics 가져오기 엔드포인트로 푸시
-v, --verboseOff에이전트의 추론 (reasoning) 및 도구 호출 (tool calls) 스트리밍
변수 (Variable)목적 (Purpose)
ANTHROPIC_API_KEYClaude API 키
OPENAI_API_KEYOpenAI API 키
OPENROUTER_API_KEYOpenRouter API 키 (openrouter/... 모델용, 예: openrouter/moonshotai/kimi-k2.6)
제공자별 키 (Provider-specific keys)최선의 노력을 다하는 pi-ai 제공자들을 위해, pi-ai가 기대하는 환경 변수를 사용하십시오 (예: MISTRAL_API_KEY, GEMINI_API_KEY, XAI_API_KEY, GROQ_API_KEY)
LLM_API_KEY일반적인 폴백 (fallback) (제공자별 키가 설정되지 않은 경우)
GITHUB_TOKEN / GITLAB_TOKENGitHub PR / GitLab MR에 댓글 게시 (--post 사용 시)
GITEA_TOKEN / FORGEJO_TOKEN비공개 저장소(private repos) 읽기 및 Gitea/Forgejo PR에 댓글 게시
GITEA_HOST / FORGEJO_HOST전체 PR URL에서 추론할 수 없는 경우의 Gitea/Forgejo 호스트 이름
AWS_PROFILE 또는 AWS_ACCESS_KEY_IDAWS Bedrock 인증 (API 키 불필요)

전체 모델/제공자 매트릭스는 docs/MODELS.md를, Kimi K2.6의 엔드 투 엔드 (end-to-end) 예제는 docs/OPENROUTER.md를 참조하십시오.

Hodor는 다음과 같은 형식의 Gitea 및 Forgejo 풀 리퀘스트 (pull request) URL을 지원합니다:

npx @mrkaran/hodor https://git.example.com/owner/repo/pulls/123

공개 저장소 (public repositories)의 경우, 토큰 없이도 메타데이터 가져오기가 작동할 수 있습니다. 비공개 저장소 (private repositories), 더 높은 API 제한 (API limits), 그리고 --post 기능을 위해서는 GITEA_TOKEN 또는 FORGEJO_TOKEN을 설정하십시오:

export GITEA_TOKEN=your-token
npx @mrkaran/hodor https://git.example.com/owner/repo/pulls/123 --post

Gitea가 소스 클론 (source clone) URL을 노출하는 경우, 포크 (Fork) PR은 PR 소스 저장소로부터 체크아웃 (checkout)됩니다. 만약 소스 브랜치나 포크가 삭제되었다면, 체크아웃은 워크스페이스 (workspace) 에러와 함께 실패합니다.

Hodor는 CI 실행 종료 시 리뷰별 메트릭 (per-review metrics)을 Prometheus Pushgateway 기본 URL 또는 VictoriaMetrics Prometheus 임포트 (import) 엔드포인트 (/api/v1/import/prometheus) 중 하나로 푸시할 수 있습니다:

hodor "$MR_OR_PR_URL" --prometheus-push "$METRICS_PUSH_URL"

CI에서 METRICS_PUSH_URL을 시크릿 (secret) 또는 변수 (variable)로 설정하고 --prometheus-push "$METRICS_PUSH_URL"을 추가하십시오.

Hodor 명령에 추가하십시오. 메트릭 (Metrics)은 최선 노력 (best-effort) 방식으로 작동합니다. 즉, 푸시 실패 시 경고 (warning)로 로그에 기록되며 리뷰 작업 (review job)을 실패시키지는 않습니다.

각 메트릭에는 platform, model, verdict가 라벨로 지정되며, PR/MR URL의 경우 project (owner/repo) 및 mr_iid/PR 번호도 포함됩니다. 내보내기(Exported)되는 메트릭에는 토큰 사용량 (token usage), 캐시 읽기/쓰기 토큰 (cache read/write tokens), 캐시 히트 비율 (cache hit ratio), 비용 (cost), 턴 (turns), 도구 호출 (tool calls), 소요 시간 (duration), 그리고 우선순위별 결과 (P0–P3)가 포함됩니다. 범용 Grafana 대시보드는 docs/grafana/에서 사용할 수 있습니다.

name: Hodor Review
on:
pull_request:
...

# .gitlab-ci.yml
workflow:
rules:
...

이 기능은 디프 (diff)에 인라인 댓글 (inline comments), 요약 노트, 통과/실패 커밋 상태 (pass/fail commit status), 그리고 MR 위젯에서 볼 수 있는 코드 품질 보고서 (code quality report)를 게시합니다.

고급 워크플로 (advanced workflows)에 대해서는 AUTOMATED_REVIEWS.md를 참조하십시오.

Hodor는 토큰 사용량을 자동으로 최적화합니다:

디프 임베딩 (Diff embedding): 200KB 미만의 PR의 경우, 디프가 프롬프트 (prompt)에 직접 임베딩되어 에이전트 턴 (agent turns)을 약 60회에서 약 5회로 단축합니다.
증분 리뷰 (Incremental reviews): 재실행 시, 마지막 Hodor 댓글 이후의 변경 사항만 리뷰합니다 (게시된 댓글의 SHA 마커를 통해 감지됨).
압축 (Compaction): 컨텍스트 (context)가 너무 커지면 SDK가 오래된 대화 턴을 자동으로 요약합니다.

Hodor는 모든 클라이언트에 적용되는 Agent Skills 컨벤션인 .agents/skills/에서 저장소별 리뷰 가이드라인을 찾아냅니다:

mkdir -p .agents/skills/review-guidelines

# .agents/skills/review-guidelines/SKILL.md
---
name: review-guidelines
...

스킬 (Skills)은 리뷰 중에 자동으로 로드됩니다. 자세한 내용은 SKILLS.md를 참조하십시오.

bun install # 의존성 설치 (Install dependencies)
bun run build # 빌드 (Build)
bun run test # 테스트 실행 (Run tests)
...

Hodor는 TypeScript로 작성되었으며 Bun에서 실행됩니다. 주요 구성 요소는 다음과 같습니다:

모듈 (Module)목적 (Purpose)
src/cli.tsCommander.js CLI 진입점 (entry point)
src/agent.ts핵심 리뷰 오케스트레이션 (orchestration), URL 파싱 (parsing), 댓글 게시
src/workspace.tsCI 감지 (detection), 리포지토리 클로닝 (cloning), 브랜치 체크아웃 (checkout)
src/prompt.ts프롬프트 (Prompt) 템플릿 구축 및 보간 (interpolation)
src/model.ts모델 문자열 파싱 (parsing), API 키 해결 (resolution)
src/gitlab.tsglab CLI를 통한 GitLab API (댓글, 인라인 노트, 초안 노트, 커밋 상태)
src/github.tsgh CLI를 통한 GitHub API
src/render.tsJSON 리뷰 출력 → 마크다운 (markdown) 렌더링
src/codequality.tsGitLab 코드 품질 위젯을 위한 CodeClimate JSON 아티팩트 (artifact)
src/metrics.ts토큰 (Token) 사용량 및 비용 포맷팅 (formatting)
templates/리뷰 프롬프트 템플릿 (JSON schema)

에이전트 런타임 (agent runtime)은 @mariozechner/pi-coding-agent에 의해 제공되며,

LLM 접근을 위해 @mariozechner/pi-ai를 사용합니다. 에이전트 세션은 읽기 전용 도구 (bash, read, grep, find, ls)와 리뷰 프롬프트를 부여받은 후, 자율적으로 PR (Pull Request)을 분석합니다.

SKILLS.md

  • 리포지토리별 리뷰 가이드라인 생성

AUTOMATED_REVIEWS.md

  • 고급 CI/CD 워크플로 (workflows)

버그를 발견하셨나요? 기능을 추가하고 싶으신가요? https://github.com/mr-karan/hodor/issues 에서 이슈 (issue)를 생성해 주세요.

MIT

AI 자동 생성 콘텐츠

본 콘텐츠는 GitHub AI Coding Assistants의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
1

댓글

0