@hanseungheon/gen-cmt

AI-powered git commit message generator using OpenRouter.
Staged 변경사항을 분석해 Conventional Commits 형식의 메시지를 자동 생성하고, 인터랙티브 프롬프트로 확인/편집/취소를 선택합니다.

---

설치 방법 (Installation)

방법 1: 프로젝트 로컬 설치 (추천) — 팀 프로젝트에서 공유

npm install @hanseungheon/gen-cmt

package.json의 scripts에 등록:

{
    "scripts": {
        "commit": "gen-cmt"
    }
}

사용:

git add .
npm run commit

---

방법 2: 전역 설치 — 어디서든 gen-cmt 명령어 사용

npm install -g @hanseungheon/gen-cmt

설치 후 어떤 Git 프로젝트에서든 바로 사용:

gen-cmt

---

방법 3: npx — 설치 없이 바로 사용

git add .
npx @hanseungheon/gen-cmt

---

API Key 설정 (필수)

OpenRouter에서 API Key를 발급받고, 프로젝트 루트에 .env.local 파일을 생성합니다:

# .env.local
OPENROUTER_API_KEY=sk-or-xxxxxxxxxxxx

.env 파일도 지원합니다. .env.local이 우선 적용됩니다.

---

설정 (Configuration)

프로젝트별 또는 전역으로 .commitai.json 파일을 통해 동작을 커스터마이즈할 수 있습니다.

우선순위

CLI 옵션 > 프로젝트 .commitai.json > 전역 ~/.commitai.json > 기본값

설정 파일 위치

범위	경로
전역 (모든 프로젝트 적용)	~/.commitai.json
프로젝트 (해당 프로젝트만 적용)	프로젝트루트/.commitai.json

설정 예시

.commitai.example.json 참고:

{
    "model": "nvidia/nemotron-3-nano-30b-a3b:free",
    "language": "ko",
    "maxFirstLineLength": 60,
    "temperature": 0.1,
    "maxTokens": 2048,
    "fallbackMessage": "chore: 코드 변경사항 커밋"
}

옵션	기본값	설명
model	nvidia/nemotron-3-nano-30b-a3b:free	OpenRouter 모델 ID
language	ko	커밋 메시지 언어 (ko, en 등)
maxFirstLineLength	60	첫 줄 최대 글자 수
temperature	0.1	창의성 수준 (0.0 ~ 1.0)
maxTokens	2048	최대 토큰 수
fallbackMessage	chore: 코드 변경사항 커밋	AI 실패 시 대체 메시지

---

사용 방법 (Usage)

git add .          # 커밋할 파일 스테이징
gen-cmt            # AI 커밋 메시지 생성

실행 시 다음과 같은 인터랙티브 프롬프트가 표시됩니다:

🤖 AI 커밋 메시지 생성 중...

----------------------------------------
feat: add user authentication with JWT

- implement login/logout endpoints
- add token refresh mechanism
----------------------------------------

이 메시지를 사용하시겠습니까? (y/e/n) [기본값: y]:

프롬프트 옵션

입력	동작
y 또는 Enter	메시지 그대로 커밋 실행
e	vim에서 메시지를 직접 편집 후 커밋
n	커밋 취소

---

CLI 옵션으로 즉석 오버라이드

설정 파일 수정 없이 일회성으로 옵션을 변경할 수 있습니다:

# 영어로 커밋 메시지 생성
gen-cmt --language en

# 다른 모델 사용
gen-cmt --model openai/gpt-4o

# 여러 옵션 동시 사용
gen-cmt --model anthropic/claude-3.5-sonnet --language en --maxFirstLineLength 72

---

무료 모델 추천

OpenRouter Free Models 참고:

모델	특징
nvidia/nemotron-3-nano-30b-a3b:free	기본값, 빠르고 무료
x-ai/grok-4.1-fast	최고 품질 (유료지만 저렴)

---

전역 설정 예시 (권장)

한 번만 설정하면 모든 프로젝트에서 API Key 없이 사용 가능:

# ~/.commitai.json 생성
cat > ~/.commitai.json << 'EOF'
{
  "apiKey": "sk-or-xxxxxxxxxxxx",
  "model": "nvidia/nemotron-3-nano-30b-a3b:free",
  "language": "ko"
}
EOF

---

이미 있는데 왜 만들었나

1. VSCode 내장 commit message 생성 기능이 불편해서
   • GitLens 자체 기능은 커스텀 프롬프트 반영이 안 됨
2. 자유롭게 컨벤션을 지정하고 싶어서
3. 커밋 메시지 작성이 생각보다 시간이 많이 걸려서, 작업 속도가 떨어짐.
4. agent 사용시에도 해당 라이브러리를 사용하면 불필요한 토큰 소모량을 줄일 수 있음.

---

License

MIT © hhhaan