smart-msg

AI 기반 Git 커밋 메시지 자동 생성 도구

staged 된 git diff 를 분석하여 Conventional Commit 형식의 메시지를 자동으로 생성합니다.
Google Gemini, Groq (Llama), OpenAI, Anthropic Claude, Ollama (로컬) 를 지원하며, 한국어와 영어 출력을 모두 제공합니다.

시작하기

단 두 단계로 모든 설정이 완료됩니다.

1. 설치

npm install -g smart-msg

Note

Node.js 18 이상이 필요합니다. nvm 사용자라면 nvm use 24 권장.

2. 로그인

sm login

다음 항목을 차례로 선택합니다.

단계	항목	선택지
1	언어 (Language)	English (기본) / 한국어 — 이후 모든 prompt 가 선택 언어로 진행
2	AI provider	Google Gemini (무료, 기본) / Groq / OpenAI / Claude / Ollama (로컬)
3	모델	provider 별 권장 모델 목록
4	메시지 강도	simple / middle / hard
5	API 키	자동으로 열린 발급 페이지에서 발급 후 입력 (Ollama 는 키 불필요)
6	글로벌 hook 설치 여부	Yes 권장 (모든 git 저장소에서 자동)

Note

첫 단계의 언어 선택 화면은 항상 영어로 표시됩니다. 한국어를 선택하시면 이후의 모든 prompt 가 한국어로 자동 전환됩니다.

설정은 ~/.smart-msg/config.json 에 저장되며, 모든 프로젝트에서 동일하게 사용됩니다.

Tip

6 단계의 글로벌 hook 을 설치하면 별도의 추가 작업 없이 모든 git 저장소에서 자동 메시지 생성이 동작합니다. 프로젝트마다 따로 설정할 필요가 없습니다.

Provider 선택 가이드

Provider	비용	키 발급	추천 대상
Groq (Llama) ⭐	무료 티어 제공	Groq Console (카드 등록 불필요)	무료 사용 권장 — 자체 LPU 인프라로 503 거의 없음 + 매우 빠름
Google Gemini	무료 티어 제공	Google AI Studio (카드 등록 불필요)	무료 티어 트래픽이 몰리면 503 자주 발생할 수 있음
Ollama (로컬) 🔒	완전 무료 (로컬)	키 불필요	인터넷 단절 / 회사 보안 환경 — 코드가 외부로 나가지 않음
OpenAI (GPT)	사용량만큼 과금 (유료)	OpenAI Platform (카드 등록 필수)	OpenAI 생태계를 이미 사용 중인 경우
Anthropic Claude	사용량만큼 과금 (유료)	Anthropic Console (카드 등록 필수)	Claude 의 메시지 품질을 선호하는 경우

Important

ChatGPT Plus / Claude Max 등 구독 결제로는 API 호출이 동작하지 않습니다. 구독 상품과 개발자 API 는 결제 시스템이 분리되어 있으며, OpenAI / Claude 를 사용하시려면 콘솔에서 별도로 카드 등록 또는 크레딧 충전이 필요합니다. 무료로 사용하시려면 Groq, Google Gemini, 또는 Ollama 를 선택하시기 바랍니다.

Note

Gemini 무료 티어는 인기 많은 시간대에 503 (high demand) 응답이 자주 발생할 수 있습니다. 자동 재시도가 적용되어 있긴 하지만 빈도가 높다면 Groq 으로 전환을 권장합니다 (sm login 다시 실행). 또는 sm config → fallback 에서 Groq 을 폴백으로 등록해두시면, Gemini 실패 시 자동으로 Groq 으로 전환합니다.

Ollama 사용 시

Ollama 는 로컬에 LLM 을 실행하는 도구입니다. 코드가 외부 서버로 전송되지 않으므로 회사 보안 환경에 적합합니다.

# 1) Ollama 설치 (https://ollama.com)
# 2) 모델 미리 받기
ollama pull llama3.2

# 3) smart-msg 등록
sm login   # provider 선택에서 'Ollama' 선택, 모델은 llama3.2 입력

기본 endpoint 는 http://localhost:11434 이며, 원격 Ollama 서버를 사용하시려면 sm config → baseUrl 에서 변경할 수 있습니다.

사용 방법

설치와 로그인이 완료되었다면, 이후의 사용은 평소 git 사용과 동일합니다.

git add .
git commit

git commit 명령을 실행하면 AI 가 staged 된 변경분을 분석하여 메시지를 자동으로 채워줍니다. 에디터(또는 IDE 커밋 창)에서 메시지를 검토한 뒤 그대로 commit 하거나 수정하여 commit 합니다.

동작 예시

$ git add .
$ git commit

# 에디터(또는 IDE 커밋 창)에 다음 메시지가 자동 입력됩니다.
feat(auth): add OAuth login flow

명령줄에서 직접 호출하는 방식 (선택)

IDE 커밋 창 대신 터미널에서 즉시 메시지를 생성하고 commit 까지 한 번에 진행하려면 다음을 사용합니다.

git add .
sm c

$ sm c

생성된 커밋 메시지:
feat(auth): add OAuth login flow

  y: 그대로 commit
  r: 메시지 다시 생성
  e: 에디터로 열어 수정 후 commit
  n: 취소
? 이 메시지로 커밋을 진행하시겠습니까? [Y/r/e/n]

y (또는 Enter) — 그대로 commit
r — AI 가 다시 메시지 생성 (최대 5회)
e — $EDITOR (또는 git core.editor) 로 메시지를 열어 수정 후 commit
n — 취소

sm c --dry-run 을 사용하면 commit 없이 메시지만 생성하여 출력합니다.

명령어

명령	설명
`sm login`	최초 설정 (언어, provider, 모델, 강도, 키, 글로벌 hook)
`sm c` _{(= sm commit)}	staged diff 로 메시지를 생성하고 즉시 commit (y/r/e/n 선택)
`sm c --dry-run`	commit 없이 메시지만 생성하여 출력
`sm c --intent "..."`	이번 변경의 "왜" 한 줄을 명시 (1.3.0+)
`sm c --skip-risk`	위험도 평가/confirm 건너뜀 (1.3.0+)
`sm c --skip-revert`	revert 감지 건너뜀 (1.3.0+)
`sm v` _{(= sm voice)}	음성 녹음 → Whisper 전사 → intent → commit (1.3.0+)
`sm v --file <path>`	미리 녹음한 오디오 파일로 전사 (1.3.0+)
`sm pr [--base <ref>]`	현재 브랜치의 base..HEAD 변경으로 PR 본문 (Summary + Test plan) 생성
`sm amend`	마지막 commit 의 메시지를 AI 로 재생성하여 amend
`sm split [--no-ai]`	큰 staged diff 분할 제안 — 로컬 휴리스틱 + AI 두 제안 (1.3.0+ 로컬 추가)
`sm style learn / show / clear`	저장소 commit 스타일 학습 → prompt 자동 반영 (1.3.0+)
`sm config`	언어/강도/모델/톤/gitmoji/autoIssue/fallback/verbose/baseUrl/intent/risk/revert/privacy 변경
`sm status`	현재 저장된 설정 + 버전(현재/최신) 비교 출력
`sm update`	npm registry 의 최신 버전으로 자체 업데이트
`sm logout`	저장된 API 키 제거 (다른 설정/hook 정보는 보존)
`sm uninstall`	모든 설정 및 hook 제거
`sm completion <shell>`	셸 자동완성 등록 스크립트 출력 (bash/zsh/powershell/clink)
`sm help [command]`	도움말 출력. 특정 명령을 인자로 주면 그 명령의 상세 도움말 (예: `sm help commit`)

sm pr 활용

# 자동 base 탐지 (origin/main → main → master → develop 순)
sm pr

# 특정 base 지정
sm pr --base origin/develop

# gh CLI 와 파이프 연결로 바로 PR 생성
sm pr | gh pr create --body-file -

sm amend 활용

# 마지막 commit 메시지가 마음에 안 들 때 (push 전)
sm amend
# → 마지막 commit 의 diff 로 새 메시지를 AI 가 생성
# → y/r/e/n 선택 후 git commit --amend

1.3.0 신규 기능

1.3.0 은 commit 워크플로우 자체를 한 단계 발전시키는 7 가지 기능을 추가했습니다. 모두 기본값에서 비차단성 (안내만, 사용자 흐름 끊지 않음) 이고 옵션으로 끄거나 강화할 수 있습니다.

1. Intent capture — 커밋 전 "왜" 한 줄 입력

diff 만 분석하면 "무엇을 바꿨는지" 는 잘 잡지만 "왜" 는 잡히지 않습니다. sm c 가 메시지 생성 직전 한 줄 의도를 받아 prompt 의 별도 블록으로 주입합니다.

sm c                          # 인터랙티브 prompt (빈 Enter 로 스킵)
sm c --intent "IE 로그인 루프 수정"  # 인라인 명시
sm c --no-intent              # prompt 강제 스킵 (always 모드도 우회)
SM_INTENT="..." sm c          # non-TTY (hook/CI) 환경용

sm config → captureIntent: ask (기본) / always (필수) / never

2. Risk score + 시간대 게이트

staged diff 의 영향도를 휴리스틱으로 1~5점 평가. DB migration, prod env, CI 설정, 큰 diff 등이 가산. 금요일 18시+ / 주말 / 야간 (22:00~06:00) 은 별도 시간대 경고.

위험도 평가:
  점수    : ★★★★☆ (4/5)
  - DB migration
  - CI/CD config
  시간대  : ⚠ 위험 시간대 (Friday 18:00+)
고위험 변경입니다. 그래도 진행하시겠습니까? [y/N]

sm config → riskCheck: warn (기본 — 4점+ AND 위험 시간대만 confirm) / on (4점+ 항상 confirm) / off

3. Auto-revert detector

sm c 가 staged 변경을 최근 N 개 (기본 20) commit 의 patch 와 비교해, 이 commit 이 과거 commit 을 (부분) 되돌리는지 감지하고 안내합니다. "fix A 했는데 며칠 뒤 무관한 작업에서 그 라인을 되돌려 A 재발" 패턴을 잡습니다.

⚠ 최근 commit 을 되돌릴 가능성 (2 건):
src/auth.ts: removes line(s) added in abc1234 "auth: persist session token"
    - session.token = token;

sm config → revertCheck: on (기본) / off. revertLookback 으로 스캔 깊이 조정.

4. Repo style learner

sm style learn 으로 저장소의 commit 메시지 스타일 (CC 채택률, 자주 쓰는 type/scope, 본문 길이, bullet 스타일, 출력 언어, 이슈 footer 형식 등) 을 학습 → ~/.smart-msg/styles/<repoKey>.json 저장 → 이후 sm c 가 prompt 에 자동 주입.

sm style learn               # 최근 200 개 분석 (--sample 으로 조정, 10~2000)
sm style show                # 현재 프로필 출력
sm style clear               # 프로필 제거

generic Conventional Commits 가 아니라 "그 팀이 쓴 듯한 톤" 이 나오게 만드는 장기 lock-in 기능.

5. Semantic split — 로컬 휴리스틱 분류

sm split 이 LLM 없이 파일 경로/내용으로 카테고리를 즉시 분류하고 권장 분할 + git 명령 시퀀스를 출력. AI 텍스트 제안과 병행 노출.

sm split            # 로컬 + AI 둘 다
sm split --no-ai    # 로컬만 (네트워크/비용 절감)

카테고리: formatting / docs / tests / ci / deps / config / typesOnly / feature. 정렬: 부수적인 것 먼저, 큰 feature 가 마지막.

6. Privacy mode — 의미 보존 PII 토큰화

기존 [REDACTED] 마스킹 위에 의미 보존 토큰화 추가. email/JWT/UUID/IP/CC/phone/auth-URL 등이 <EMAIL_1>, <UUID_1>, ... 형태로 치환되며 같은 값은 같은 토큰. 모델이 의미를 잃지 않고 메시지 작성 가능.

sm config → privacyMode: off / standard (기본 — 보편 PII) / strict (+일반 URL +Bearer)

IPv4 옥텟 검증 + 신용카드 Luhn 검증으로 false positive 차단.

7. Voice-driven commit

sm v (alias sm voice) — ffmpeg 마이크 녹음 또는 --file 입력 → Whisper API 전사 → 그 텍스트를 intent 로 사용해 sm c 흐름 진입. 큰 변경에 긴 본문이 필요할 때 typing 비용 0.

sm v                         # 10초 녹음
sm v --seconds 20            # 20초 녹음
sm v --file pre-recorded.wav # ffmpeg 불필요
sm v --dry-run               # 메시지만 출력

OpenAI 키 필요 (메인 provider 가 openai 가 아니어도 openaiApiKey 만 있으면 동작). 10 초 클립 비용 ≈ $0.0001 USD.

옵션

Provider 별 권장 모델

Provider	권장 모델
Gemini	`gemini-2.5-flash`, `gemini-2.5-flash-lite`, `gemini-2.0-flash`
Groq	`llama-3.1-8b-instant`, `llama-3.3-70b-versatile`, `gemma2-9b-it`
OpenAI	`gpt-4.1-nano`, `gpt-4o-mini`, `gpt-4.1-mini`
Claude	`claude-haiku-4-5`, `claude-3-5-haiku-latest`
Ollama	`llama3.2`, `qwen2.5-coder`, `mistral`, `phi3` (또는 직접 입력)

Language

값	출력 언어
`ko`	한국어 (`feat`, `fix` 등 type 키워드는 영어 유지)
`en`	영어

Strength

메시지의 길이와 상세도를 결정합니다.

simple — 한 줄 (Conventional Commit 형식)

feat(auth): add OAuth login flow

middle — 첫 줄 + 본문 2~5줄

feat(auth): add OAuth login flow

- PKCE 기반 OAuth 콜백 처리 추가
- 로컬 콜백 서버를 임시로 생성
- 발급된 토큰을 ~/.smart-msg/config.json 에 저장

hard — 첫 줄 + README 수준 본문

feat(auth): add OAuth login flow

기존 API 키 입력 방식은 매번 발급 페이지로 이동하여 복사 및 붙여넣기를
수행하는 부담이 있었습니다. 표준 OAuth 흐름을 도입하여 이를 해소합니다.

- PKCE flow 로 토큰을 안전하게 획득
- 로컬 8765 포트에 임시 콜백 서버 운영
- 토큰은 OS keychain 에 보관
- 토큰 만료 시 자동 갱신

영향: 기존 API 키 사용자의 동작은 변경되지 않습니다.

Tone (한국어 출력 종결 톤)

한국어 출력에만 적용되는 본문 종결 스타일입니다. 영어 출력에는 영향이 없습니다.

값	출력 예시
`report` (기본)	`메뉴 항목 추가`, `엔드포인트 분리`, `스레드 풀 제거. 필요 시 추후 확장.` (명사형/음슴체)
`polite`	`~를 추가했습니다.`, `~로 변경했습니다.`, `~를 분리하기 위해 변경했습니다.` (정중체)

sm config → tone 메뉴에서 변경 가능합니다.

Note

신규 설치 + 기존 설치(미설정) 모두 report 톤이 기본 적용됩니다. commit 메시지는 짧은 기술 보고서 톤이 자연스럽다는 판단입니다. 정중체를 원하시면 sm config 에서 polite 로 전환하시기 바랍니다.

Gitmoji (이모지 prefix)

sm config → gitmoji 를 on 으로 설정하면 commit type 앞에 이모지가 자동으로 붙습니다.

✨ feat(auth): add OAuth login flow
🐛 fix(parser): handle empty input
♻️ refactor(api): split endpoint by pageType

매핑: feat → ✨, fix → 🐛, docs → 📝, refactor → ♻️, perf → ⚡️, test → ✅, chore → 🔧, build → 📦, style → 💄

Auto Issue (브랜치명 → 이슈키 footer 자동 첨부)

sm config → autoIssue 를 on 으로 설정하면 현재 브랜치명에서 이슈 키를 추출하여 commit 메시지 footer 에 Refs: 로 자동 첨부합니다.

git checkout -b feature/AUTH-123-oauth-login
git add .
sm c
# →
# feat(auth): add OAuth login flow
#
# - PKCE 기반 OAuth 콜백 처리 추가
# ...
#
# Refs: AUTH-123

추출 패턴:

JIRA 류: AUTH-123, PROJ-9999 등 (대문자 prefix + 숫자)
GitHub 류: #123, gh-123, issue-123, issue/123 등

Fallback Provider

sm config → fallback 에서 폴백 provider 를 등록하면, 메인 provider 가 실패 (503, timeout 등) 했을 때 자동으로 다른 provider 로 재시도합니다.

provider : gemini    ← 메인
fallback : groq      ← Gemini 503 시 자동으로 Groq 호출

두 provider 의 키가 모두 sm login 으로 등록되어 있어야 동작합니다.

Verbose / 디버그

문제 진단이 필요할 때 sm config → verbose 를 on 으로 설정하면 prompt 와 응답이 stderr 에 출력됩니다. 환경변수로도 활성화 가능합니다.

SM_DEBUG=1 sm c

Diff 마스킹 (자동)

.env 류의 secret, AWS/GitHub 토큰, PEM private key 등은 AI 에 보내기 전 자동으로 [REDACTED] 로 마스킹됩니다. 사용자가 실수로 secret 을 staged 한 경우의 1차 방어선입니다.

Warning

마스킹은 완전한 보호 수단이 아닙니다. secret 파일은 .gitignore 처리하는 것이 우선입니다.

On-failure (AI 호출 실패 시 동작)

값	동작
`fallback` (기본)	안내 코멘트가 담긴 빈 템플릿을 적어 git 에디터가 열림. 사용자가 직접 메시지 작성 가능
`abort`	메시지를 비워둬 git 이 commit 자체를 취소

sm config → on-failure 메뉴에서 변경 가능.

Note

Gemini 의 503 (high demand), 일시 네트워크 단절 등으로 AI 메시지 생성이 실패하는 경우가 있습니다. 자동 재시도(429/5xx 대상, 백오프 0.6초·1.2초, 단일 호출 30초 타임아웃) + 폴백 provider (등록 시) 가 1차 방어선이며, 그래도 실패한 경우 위 옵션이 적용됩니다.

Custom Base URL (Azure OpenAI / 원격 Ollama 등)

sm config → baseUrl 에서 OpenAI 호환 endpoint 또는 원격 Ollama 서버의 URL 을 지정할 수 있습니다.

OpenAI: Azure OpenAI, OpenRouter, 자체 호스팅 vLLM 등에 사용 (https://your-resource.openai.azure.com/...)
Ollama: 원격 머신에서 실행 중인 Ollama (http://192.168.1.10:11434)

설정 변경

sm config

메뉴에서 변경할 항목을 선택합니다. provider 자체를 바꾸려면 sm login 을 다시 실행합니다 (다른 provider 의 키는 보존됩니다).

업데이트

sm update

sm update 를 실행하면 현재 버전과 npm registry 의 최신 버전을 비교한 뒤, 다른 경우에 한해 자동으로 npm install -g smart-msg@latest 를 수행합니다.

수동으로 진행하시려면 다음과 동일합니다.

npm install -g smart-msg@latest

버전 확인

sm --version       # 현재 버전만 출력
sm status          # 현재 버전 + 최신 버전 비교 + 설정 정보 함께 출력

sm status 출력 예시:

provider : gemini
model    : gemini-2.5-flash
language : ko
strength : middle
tone     : report
gitmoji  : off
autoIssue: on
fallback : groq
onFail   : fallback
verbose  : off
config   : C:\Users\you\.smart-msg\config.json
version  : 1.1.54 → latest 1.2.0  ⇣  run `sm update` to upgrade

Note

업데이트 후에도 기존 ~/.smart-msg/config.json 의 설정과 API 키는 그대로 유지됩니다. 다시 로그인할 필요가 없습니다.

새로 추가된 provider (예: Ollama) 를 사용하려면 sm login 을 다시 실행하여 추가 키를 등록할 수 있습니다. 기존 키는 덮어쓰여지지 않습니다.

자동완성

sm <TAB> 입력 시 서브커맨드(login, logout, commit, pr, amend, split 등) 가 자동으로 완성되도록 셸별 등록 스크립트를 제공합니다.

bash

echo 'eval "$(sm completion bash)"' >> ~/.bashrc
source ~/.bashrc

zsh

echo 'eval "$(sm completion zsh)"' >> ~/.zshrc
source ~/.zshrc

PowerShell

sm completion powershell | Out-String | Invoke-Expression

영구 적용을 원하시는 경우 위 줄을 $PROFILE 파일에 추가합니다. (notepad $PROFILE)

clink (Windows cmd 사용자)

cmd.exe 자체는 사용자 정의 자동완성을 지원하지 않습니다. clink 를 설치하시면 cmd 위에서도 자동완성이 동작합니다.

sm completion clink > %LOCALAPPDATA%\clink\sm.lua

새 cmd 창부터 자동완성이 적용됩니다.

Note

순수 cmd.exe 는 자동완성을 지원하지 않습니다. PowerShell 또는 clink 를 사용하시기 바랍니다.

지원 환경

smart-msg 는 git 명령이 동작하는 모든 환경에서 동일하게 사용할 수 있습니다.

터미널

Git Bash, PowerShell, Windows CMD, macOS Terminal, iTerm2, Linux Bash / Zsh 모두 별도 설정 없이 동작합니다.

Note

PowerShell 에서 sm 실행이 차단되는 경우 다음 명령으로 정책을 완화합니다.

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

IDE

IDE	사용 방법
IntelliJ IDEA / WebStorm / PyCharm	`Ctrl + K` 로 커밋 창을 열면 메시지가 자동으로 채워집니다
VS Code, Cursor	`Ctrl + Shift + G` 로 Source Control 패널을 열고 commit 시 메시지가 자동으로 채워집니다
그 외 IDE	내장 터미널이 있는 모든 IDE 에서 동일하게 동작합니다

Tip

IDE 커밋 창 통합은 sm login 의 마지막 단계에서 글로벌 hook 을 설치한 경우에만 동작합니다. 설치하지 않은 경우 sm login 을 다시 실행하여 활성화할 수 있습니다.

비 Node.js 프로젝트

smart-msg 는 글로벌 CLI 이므로 프로젝트 언어와 무관하게 동작합니다. Java, Python, Go 등 어떤 언어 프로젝트에서도 동일하게 사용할 수 있으며, node_modules 폴더가 프로젝트에 생성되지 않습니다.

제거

sm uninstall
npm uninstall -g smart-msg

sm uninstall 이 다음 항목을 모두 정리합니다.

설정 디렉토리 (~/.smart-msg/)
글로벌 git hook 설정 (이전 값이 있다면 복원)
프로젝트별 설치된 hook (있는 경우)

이후 npm uninstall -g smart-msg 로 패키지 본체를 제거하면 완전히 정리됩니다.

Warning

npm 은 글로벌 패키지 uninstall 시 lifecycle script 의 실행을 차단합니다. sm uninstall 을 먼저 실행하지 않으면 ~/.smart-msg/ 가 그대로 남아 API 키도 보존됩니다.

License

ISC

_{Built with TypeScript · Powered by Google Gemini, Groq, OpenAI, Anthropic Claude & Ollama}

Name		Name	Last commit message	Last commit date
Latest commit History 45 Commits
.github/workflows		.github/workflows
src		src
test		test
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

smart-msg

목차

시작하기

1. 설치

2. 로그인

Provider 선택 가이드

Ollama 사용 시

사용 방법

동작 예시

명령줄에서 직접 호출하는 방식 (선택)

명령어

sm pr 활용

sm amend 활용

1.3.0 신규 기능

1. Intent capture — 커밋 전 "왜" 한 줄 입력

2. Risk score + 시간대 게이트

3. Auto-revert detector

4. Repo style learner

5. Semantic split — 로컬 휴리스틱 분류

6. Privacy mode — 의미 보존 PII 토큰화

7. Voice-driven commit

옵션

Provider 별 권장 모델

Language

Strength

Tone (한국어 출력 종결 톤)

Gitmoji (이모지 prefix)

Auto Issue (브랜치명 → 이슈키 footer 자동 첨부)

Fallback Provider

Verbose / 디버그

Diff 마스킹 (자동)

On-failure (AI 호출 실패 시 동작)

Custom Base URL (Azure OpenAI / 원격 Ollama 등)

설정 변경

업데이트

버전 확인

자동완성

bash

zsh

PowerShell

clink (Windows cmd 사용자)

지원 환경

터미널

IDE

비 Node.js 프로젝트

제거

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages