목차

시작하기

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

1. 설치

npm install -g smart-msg

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

2. 로그인

sm login

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

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

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

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

Provider 선택 가이드

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

[!NOTE] Gemini 무료 티어는 인기 많은 시간대에 503 (high demand) 응답이 자주 발생할 수 있습니다. 자동 재시도가 적용되어 있긴 하지만 빈도가 높다면 Groq 으로 전환을 권장합니다 (sm login 다시 실행). Groq 은 자체 LPU 인프라를 사용해 무료 티어에서도 503 빈도가 매우 낮고 응답 속도도 5~10배 빠릅니다.

사용 방법

설치와 로그인이 완료되었다면, 이후의 사용은 평소 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/n)

명령어

옵션

Provider 별 권장 모델

Language

Strength

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

feat(auth): add OAuth login flow

feat(auth): add OAuth login flow

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

feat(auth): add OAuth login flow

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

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

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

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

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

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

설정 변경

sm config

메뉴에서 언어, 강도, 모델, on-failure 중 하나를 선택하여 변경합니다. 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
config   : C:\Users\you\.smart-msg\config.json
version  : 1.1.50 → latest 1.1.51  ⇣  run `sm update` to upgrade

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

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

자동완성

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

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

[!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