{"id":51282722,"url":"https://github.com/black-astro/smart-msg","last_synced_at":"2026-06-30T03:03:18.505Z","repository":{"id":354317036,"uuid":"1223096445","full_name":"black-astro/smart-msg","owner":"black-astro","description":"AI Git commit message generator with multi-provider support (OpenAI, Claude, Gemini, Groq, Ollama). Korean/English output, Conventional Commits format.","archived":false,"fork":false,"pushed_at":"2026-05-27T04:15:09.000Z","size":448,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T04:20:03.920Z","etag":null,"topics":["ai","claude","cli","commit","commit-message","conventional-commits","developer-tools","gemini","git","git-commit","groq","korean","llm","nodejs","ollama","openai","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/smart-msg","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/black-astro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-28T02:17:32.000Z","updated_at":"2026-05-27T04:13:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/black-astro/smart-msg","commit_stats":null,"previous_names":["black-astro/smart-msg"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/black-astro/smart-msg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/black-astro%2Fsmart-msg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/black-astro%2Fsmart-msg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/black-astro%2Fsmart-msg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/black-astro%2Fsmart-msg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/black-astro","download_url":"https://codeload.github.com/black-astro/smart-msg/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/black-astro%2Fsmart-msg/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34950347,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude","cli","commit","commit-message","conventional-commits","developer-tools","gemini","git","git-commit","groq","korean","llm","nodejs","ollama","openai","typescript"],"created_at":"2026-06-30T03:03:16.613Z","updated_at":"2026-06-30T03:03:18.498Z","avatar_url":"https://github.com/black-astro.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# smart-msg\n\n**AI 기반 Git 커밋 메시지 자동 생성 도구**\n\nstaged 된 git diff 를 분석하여 Conventional Commit 형식의 메시지를 자동으로 생성합니다.\u003cbr\u003e\nGoogle Gemini, Groq (Llama), OpenAI, Anthropic Claude, Ollama (로컬) 를 지원하며, 한국어와 영어 출력을 모두 제공합니다.\n\n\u003cbr\u003e\n\n[![version](https://img.shields.io/badge/version-1.3.0-555555?style=flat-square)](https://www.npmjs.com/package/smart-msg)\n[![license](https://img.shields.io/badge/license-ISC-555555?style=flat-square)](#license)\n[![node](https://img.shields.io/badge/node-%3E%3D18-555555?style=flat-square)](https://nodejs.org)\n[![Groq](https://img.shields.io/badge/Groq-free%20tier-F55036?style=flat-square)](https://console.groq.com)\n[![Gemini](https://img.shields.io/badge/Gemini-free%20tier-34A853?style=flat-square)](https://aistudio.google.com)\n[![Ollama](https://img.shields.io/badge/Ollama-local-000000?style=flat-square)](https://ollama.com)\n[![OpenAI](https://img.shields.io/badge/OpenAI-supported-black?style=flat-square)](https://platform.openai.com)\n[![Claude](https://img.shields.io/badge/Claude-supported-black?style=flat-square)](https://www.anthropic.com)\n\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n---\n\n## 목차\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n- [시작하기](#시작하기)\n- [Provider 선택 가이드](#provider-선택-가이드)\n- [사용 방법](#사용-방법)\n- [명령어](#명령어)\n- [1.3.0 신규 기능](#130-신규-기능)\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n- [옵션](#옵션)\n- [업데이트](#업데이트)\n- [자동완성](#자동완성)\n- [지원 환경](#지원-환경)\n- [제거](#제거)\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cbr\u003e\n\n---\n\n## 시작하기\n\n단 두 단계로 모든 설정이 완료됩니다.\n\n### 1. 설치\n\n```bash\nnpm install -g smart-msg\n```\n\n\u003e [!NOTE]\n\u003e Node.js 18 이상이 필요합니다. nvm 사용자라면 `nvm use 24` 권장.\n\n### 2. 로그인\n\n```bash\nsm login\n```\n\n다음 항목을 차례로 선택합니다.\n\n|  단계  | 항목                  | 선택지                                                |\n| :--: | ------------------- | -------------------------------------------------- |\n|  1   | **언어 (Language)**   | **English (기본)** / 한국어 — 이후 모든 prompt 가 선택 언어로 진행 |\n|  2   | AI provider         | **Google Gemini (무료, 기본)** / Groq / OpenAI / Claude / Ollama (로컬) |\n|  3   | 모델                  | provider 별 권장 모델 목록                                  |\n|  4   | 메시지 강도              | simple / middle / hard                             |\n|  5   | API 키               | 자동으로 열린 발급 페이지에서 발급 후 입력 (Ollama 는 키 불필요)            |\n|  6   | 글로벌 hook 설치 여부      | **Yes** 권장 (모든 git 저장소에서 자동)                       |\n\n\u003e [!NOTE]\n\u003e 첫 단계의 언어 선택 화면은 항상 영어로 표시됩니다. 한국어를 선택하시면 이후의 모든 prompt 가 한국어로 자동 전환됩니다.\n\n설정은 `~/.smart-msg/config.json` 에 저장되며, 모든 프로젝트에서 동일하게 사용됩니다.\n\n\u003e [!TIP]\n\u003e 6 단계의 글로벌 hook 을 설치하면 별도의 추가 작업 없이 모든 git 저장소에서 자동 메시지 생성이 동작합니다. 프로젝트마다 따로 설정할 필요가 없습니다.\n\n\u003cbr\u003e\n\n---\n\n## Provider 선택 가이드\n\n| Provider                | 비용                | 키 발급                                              | 추천 대상                              |\n| ----------------------- | ----------------- | ------------------------------------------------- | ---------------------------------- |\n| **Groq (Llama)** ⭐      | 무료 티어 제공          | [Groq Console](https://console.groq.com/keys) (카드 등록 불필요) | **무료 사용 권장** — 자체 LPU 인프라로 503 거의 없음 + 매우 빠름 |\n| Google Gemini           | 무료 티어 제공          | [Google AI Studio](https://aistudio.google.com/app/apikey) (카드 등록 불필요) | 무료 티어 트래픽이 몰리면 503 자주 발생할 수 있음     |\n| **Ollama (로컬)** 🔒      | 완전 무료 (로컬)        | 키 불필요                                            | 인터넷 단절 / 회사 보안 환경 — 코드가 외부로 나가지 않음 |\n| OpenAI (GPT)            | 사용량만큼 과금 (유료)     | [OpenAI Platform](https://platform.openai.com/api-keys) (카드 등록 필수)    | OpenAI 생태계를 이미 사용 중인 경우            |\n| Anthropic Claude        | 사용량만큼 과금 (유료)     | [Anthropic Console](https://console.anthropic.com/settings/keys) (카드 등록 필수) | Claude 의 메시지 품질을 선호하는 경우           |\n\n\u003e [!IMPORTANT]\n\u003e **ChatGPT Plus / Claude Max 등 구독 결제로는 API 호출이 동작하지 않습니다.** 구독 상품과 개발자 API 는 결제 시스템이 분리되어 있으며, OpenAI / Claude 를 사용하시려면 콘솔에서 별도로 카드 등록 또는 크레딧 충전이 필요합니다. **무료로 사용하시려면 Groq, Google Gemini, 또는 Ollama 를 선택하시기 바랍니다.**\n\n\u003e [!NOTE]\n\u003e Gemini 무료 티어는 인기 많은 시간대에 503 (high demand) 응답이 자주 발생할 수 있습니다. 자동 재시도가 적용되어 있긴 하지만 빈도가 높다면 **Groq 으로 전환**을 권장합니다 (`sm login` 다시 실행). 또는 `sm config` → `fallback` 에서 Groq 을 폴백으로 등록해두시면, Gemini 실패 시 자동으로 Groq 으로 전환합니다.\n\n### Ollama 사용 시\n\nOllama 는 로컬에 LLM 을 실행하는 도구입니다. 코드가 외부 서버로 전송되지 않으므로 회사 보안 환경에 적합합니다.\n\n```bash\n# 1) Ollama 설치 (https://ollama.com)\n# 2) 모델 미리 받기\nollama pull llama3.2\n\n# 3) smart-msg 등록\nsm login   # provider 선택에서 'Ollama' 선택, 모델은 llama3.2 입력\n```\n\n기본 endpoint 는 `http://localhost:11434` 이며, 원격 Ollama 서버를 사용하시려면 `sm config` → `baseUrl` 에서 변경할 수 있습니다.\n\n\u003cbr\u003e\n\n---\n\n## 사용 방법\n\n설치와 로그인이 완료되었다면, 이후의 사용은 평소 git 사용과 동일합니다.\n\n```bash\ngit add .\ngit commit\n```\n\n`git commit` 명령을 실행하면 AI 가 staged 된 변경분을 분석하여 메시지를 자동으로 채워줍니다. 에디터(또는 IDE 커밋 창)에서 메시지를 검토한 뒤 그대로 commit 하거나 수정하여 commit 합니다.\n\n### 동작 예시\n\n```text\n$ git add .\n$ git commit\n\n# 에디터(또는 IDE 커밋 창)에 다음 메시지가 자동 입력됩니다.\nfeat(auth): add OAuth login flow\n```\n\n### 명령줄에서 직접 호출하는 방식 (선택)\n\nIDE 커밋 창 대신 터미널에서 즉시 메시지를 생성하고 commit 까지 한 번에 진행하려면 다음을 사용합니다.\n\n```bash\ngit add .\nsm c\n```\n\n```text\n$ sm c\n\n생성된 커밋 메시지:\nfeat(auth): add OAuth login flow\n\n  y: 그대로 commit\n  r: 메시지 다시 생성\n  e: 에디터로 열어 수정 후 commit\n  n: 취소\n? 이 메시지로 커밋을 진행하시겠습니까? [Y/r/e/n]\n```\n\n- `y` (또는 Enter) — 그대로 commit\n- `r` — AI 가 다시 메시지 생성 (최대 5회)\n- `e` — `$EDITOR` (또는 git core.editor) 로 메시지를 열어 수정 후 commit\n- `n` — 취소\n\n`sm c --dry-run` 을 사용하면 commit 없이 메시지만 생성하여 출력합니다.\n\n\u003cbr\u003e\n\n---\n\n## 명령어\n\n| 명령                          | 설명                                                  |\n| --------------------------- | --------------------------------------------------- |\n| `sm login`                  | 최초 설정 (언어, provider, 모델, 강도, 키, 글로벌 hook)            |\n| `sm c` \u003csub\u003e(= `sm commit`)\u003c/sub\u003e | staged diff 로 메시지를 생성하고 즉시 commit (y/r/e/n 선택)   |\n| `sm c --dry-run`            | commit 없이 메시지만 생성하여 출력                              |\n| `sm c --intent \"...\"`       | 이번 변경의 \"왜\" 한 줄을 명시 (1.3.0+)                          |\n| `sm c --skip-risk`          | 위험도 평가/confirm 건너뜀 (1.3.0+)                          |\n| `sm c --skip-revert`        | revert 감지 건너뜀 (1.3.0+)                                |\n| `sm v` \u003csub\u003e(= `sm voice`)\u003c/sub\u003e | 음성 녹음 → Whisper 전사 → intent → commit (1.3.0+)      |\n| `sm v --file \u003cpath\u003e`        | 미리 녹음한 오디오 파일로 전사 (1.3.0+)                           |\n| `sm pr [--base \u003cref\u003e]`      | 현재 브랜치의 base..HEAD 변경으로 PR 본문 (Summary + Test plan) 생성 |\n| `sm amend`                  | 마지막 commit 의 메시지를 AI 로 재생성하여 amend                  |\n| `sm split [--no-ai]`        | 큰 staged diff 분할 제안 — 로컬 휴리스틱 + AI 두 제안 (1.3.0+ 로컬 추가) |\n| `sm style learn / show / clear` | 저장소 commit 스타일 학습 → prompt 자동 반영 (1.3.0+)         |\n| `sm config`                 | 언어/강도/모델/톤/gitmoji/autoIssue/fallback/verbose/baseUrl/intent/risk/revert/privacy 변경 |\n| `sm status`                 | 현재 저장된 설정 + 버전(현재/최신) 비교 출력                          |\n| `sm update`                 | npm registry 의 최신 버전으로 자체 업데이트                       |\n| `sm logout`                 | 저장된 API 키 제거 (다른 설정/hook 정보는 보존)                   |\n| `sm uninstall`              | 모든 설정 및 hook 제거                                    |\n| `sm completion \u003cshell\u003e`     | 셸 자동완성 등록 스크립트 출력 (bash/zsh/powershell/clink)        |\n| `sm help [command]`         | 도움말 출력. 특정 명령을 인자로 주면 그 명령의 상세 도움말 (예: `sm help commit`) |\n\n### sm pr 활용\n\n```bash\n# 자동 base 탐지 (origin/main → main → master → develop 순)\nsm pr\n\n# 특정 base 지정\nsm pr --base origin/develop\n\n# gh CLI 와 파이프 연결로 바로 PR 생성\nsm pr | gh pr create --body-file -\n```\n\n### sm amend 활용\n\n```bash\n# 마지막 commit 메시지가 마음에 안 들 때 (push 전)\nsm amend\n# → 마지막 commit 의 diff 로 새 메시지를 AI 가 생성\n# → y/r/e/n 선택 후 git commit --amend\n```\n\n\u003cbr\u003e\n\n---\n\n## 1.3.0 신규 기능\n\n1.3.0 은 commit 워크플로우 자체를 한 단계 발전시키는 7 가지 기능을 추가했습니다. 모두 **기본값에서 비차단성** (안내만, 사용자 흐름 끊지 않음) 이고 옵션으로 끄거나 강화할 수 있습니다.\n\n### 1. Intent capture — 커밋 전 \"왜\" 한 줄 입력\n\ndiff 만 분석하면 \"무엇을 바꿨는지\" 는 잘 잡지만 \"왜\" 는 잡히지 않습니다. `sm c` 가 메시지 생성 직전 한 줄 의도를 받아 prompt 의 별도 블록으로 주입합니다.\n\n```bash\nsm c                          # 인터랙티브 prompt (빈 Enter 로 스킵)\nsm c --intent \"IE 로그인 루프 수정\"  # 인라인 명시\nsm c --no-intent              # prompt 강제 스킵 (always 모드도 우회)\nSM_INTENT=\"...\" sm c          # non-TTY (hook/CI) 환경용\n```\n\n`sm config` → `captureIntent`: `ask` (기본) / `always` (필수) / `never`\n\n### 2. Risk score + 시간대 게이트\n\nstaged diff 의 영향도를 휴리스틱으로 **1~5점** 평가. DB migration, prod env, CI 설정, 큰 diff 등이 가산. 금요일 18시+ / 주말 / 야간 (22:00~06:00) 은 별도 **시간대 경고**.\n\n```\n위험도 평가:\n  점수    : ★★★★☆ (4/5)\n  - DB migration\n  - CI/CD config\n  시간대  : ⚠ 위험 시간대 (Friday 18:00+)\n고위험 변경입니다. 그래도 진행하시겠습니까? [y/N]\n```\n\n`sm config` → `riskCheck`: `warn` (기본 — 4점+ AND 위험 시간대만 confirm) / `on` (4점+ 항상 confirm) / `off`\n\n### 3. Auto-revert detector\n\n`sm c` 가 staged 변경을 **최근 N 개 (기본 20) commit** 의 patch 와 비교해, 이 commit 이 과거 commit 을 (부분) 되돌리는지 감지하고 안내합니다. \"fix A 했는데 며칠 뒤 무관한 작업에서 그 라인을 되돌려 A 재발\" 패턴을 잡습니다.\n\n```\n⚠ 최근 commit 을 되돌릴 가능성 (2 건):\nsrc/auth.ts: removes line(s) added in abc1234 \"auth: persist session token\"\n    - session.token = token;\n```\n\n`sm config` → `revertCheck`: `on` (기본) / `off`. `revertLookback` 으로 스캔 깊이 조정.\n\n### 4. Repo style learner\n\n`sm style learn` 으로 저장소의 commit 메시지 스타일 (CC 채택률, 자주 쓰는 type/scope, 본문 길이, bullet 스타일, 출력 언어, 이슈 footer 형식 등) 을 학습 → `~/.smart-msg/styles/\u003crepoKey\u003e.json` 저장 → 이후 `sm c` 가 prompt 에 **자동 주입**.\n\n```bash\nsm style learn               # 최근 200 개 분석 (--sample 으로 조정, 10~2000)\nsm style show                # 현재 프로필 출력\nsm style clear               # 프로필 제거\n```\n\ngeneric Conventional Commits 가 아니라 **\"그 팀이 쓴 듯한 톤\"** 이 나오게 만드는 장기 lock-in 기능.\n\n### 5. Semantic split — 로컬 휴리스틱 분류\n\n`sm split` 이 LLM 없이 파일 경로/내용으로 카테고리를 즉시 분류하고 권장 분할 + git 명령 시퀀스를 출력. AI 텍스트 제안과 **병행** 노출.\n\n```bash\nsm split            # 로컬 + AI 둘 다\nsm split --no-ai    # 로컬만 (네트워크/비용 절감)\n```\n\n카테고리: `formatting` / `docs` / `tests` / `ci` / `deps` / `config` / `typesOnly` / `feature`. 정렬: 부수적인 것 먼저, 큰 feature 가 마지막.\n\n### 6. Privacy mode — 의미 보존 PII 토큰화\n\n기존 `[REDACTED]` 마스킹 위에 **의미 보존 토큰화** 추가. email/JWT/UUID/IP/CC/phone/auth-URL 등이 `\u003cEMAIL_1\u003e`, `\u003cUUID_1\u003e`, ... 형태로 치환되며 **같은 값은 같은 토큰**. 모델이 의미를 잃지 않고 메시지 작성 가능.\n\n`sm config` → `privacyMode`: `off` / `standard` (기본 — 보편 PII) / `strict` (+일반 URL +Bearer)\n\nIPv4 옥텟 검증 + 신용카드 Luhn 검증으로 false positive 차단.\n\n### 7. Voice-driven commit\n\n`sm v` (alias `sm voice`) — ffmpeg 마이크 녹음 또는 `--file` 입력 → Whisper API 전사 → 그 텍스트를 intent 로 사용해 `sm c` 흐름 진입. 큰 변경에 긴 본문이 필요할 때 typing 비용 0.\n\n```bash\nsm v                         # 10초 녹음\nsm v --seconds 20            # 20초 녹음\nsm v --file pre-recorded.wav # ffmpeg 불필요\nsm v --dry-run               # 메시지만 출력\n```\n\nOpenAI 키 필요 (메인 provider 가 openai 가 아니어도 `openaiApiKey` 만 있으면 동작). 10 초 클립 비용 ≈ **$0.0001 USD**.\n\n\u003cbr\u003e\n\n---\n\n## 옵션\n\n### Provider 별 권장 모델\n\n| Provider | 권장 모델                                                                          |\n| -------- | ------------------------------------------------------------------------------ |\n| Gemini   | `gemini-2.5-flash`, `gemini-2.5-flash-lite`, `gemini-2.0-flash`                |\n| Groq     | `llama-3.1-8b-instant`, `llama-3.3-70b-versatile`, `gemma2-9b-it`              |\n| OpenAI   | `gpt-4.1-nano`, `gpt-4o-mini`, `gpt-4.1-mini`                                  |\n| Claude   | `claude-haiku-4-5`, `claude-3-5-haiku-latest`                                  |\n| Ollama   | `llama3.2`, `qwen2.5-coder`, `mistral`, `phi3` (또는 직접 입력)                    |\n\n### Language\n\n|  값  | 출력 언어                                          |\n| :-: | ---------------------------------------------- |\n| `ko` | 한국어 (`feat`, `fix` 등 type 키워드는 영어 유지) |\n| `en` | 영어                                            |\n\n\u003cbr\u003e\n\n### Strength\n\n메시지의 길이와 상세도를 결정합니다.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003esimple\u003c/b\u003e \u0026nbsp;—\u0026nbsp; 한 줄 (Conventional Commit 형식)\u003c/summary\u003e\n\n\u003cbr\u003e\n\n```\nfeat(auth): add OAuth login flow\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003emiddle\u003c/b\u003e \u0026nbsp;—\u0026nbsp; 첫 줄 + 본문 2~5줄\u003c/summary\u003e\n\n\u003cbr\u003e\n\n```\nfeat(auth): add OAuth login flow\n\n- PKCE 기반 OAuth 콜백 처리 추가\n- 로컬 콜백 서버를 임시로 생성\n- 발급된 토큰을 ~/.smart-msg/config.json 에 저장\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ehard\u003c/b\u003e \u0026nbsp;—\u0026nbsp; 첫 줄 + README 수준 본문\u003c/summary\u003e\n\n\u003cbr\u003e\n\n```\nfeat(auth): add OAuth login flow\n\n기존 API 키 입력 방식은 매번 발급 페이지로 이동하여 복사 및 붙여넣기를\n수행하는 부담이 있었습니다. 표준 OAuth 흐름을 도입하여 이를 해소합니다.\n\n- PKCE flow 로 토큰을 안전하게 획득\n- 로컬 8765 포트에 임시 콜백 서버 운영\n- 토큰은 OS keychain 에 보관\n- 토큰 만료 시 자동 갱신\n\n영향: 기존 API 키 사용자의 동작은 변경되지 않습니다.\n```\n\n\u003c/details\u003e\n\n### Tone (한국어 출력 종결 톤)\n\n한국어 출력에만 적용되는 본문 종결 스타일입니다. 영어 출력에는 영향이 없습니다.\n\n|  값        | 출력 예시                                                    |\n| --------- | -------------------------------------------------------- |\n| `report` (기본) | `메뉴 항목 추가`, `엔드포인트 분리`, `스레드 풀 제거. 필요 시 추후 확장.` (명사형/음슴체) |\n| `polite`  | `~를 추가했습니다.`, `~로 변경했습니다.`, `~를 분리하기 위해 변경했습니다.` (정중체)  |\n\n`sm config` → `tone` 메뉴에서 변경 가능합니다.\n\n\u003e [!NOTE]\n\u003e 신규 설치 + 기존 설치(미설정) 모두 `report` 톤이 기본 적용됩니다. commit 메시지는 짧은 기술 보고서 톤이 자연스럽다는 판단입니다. 정중체를 원하시면 `sm config` 에서 `polite` 로 전환하시기 바랍니다.\n\n### Gitmoji (이모지 prefix)\n\n`sm config` → `gitmoji` 를 `on` 으로 설정하면 commit type 앞에 이모지가 자동으로 붙습니다.\n\n```\n✨ feat(auth): add OAuth login flow\n🐛 fix(parser): handle empty input\n♻️ refactor(api): split endpoint by pageType\n```\n\n매핑: `feat → ✨`, `fix → 🐛`, `docs → 📝`, `refactor → ♻️`, `perf → ⚡️`, `test → ✅`, `chore → 🔧`, `build → 📦`, `style → 💄`\n\n### Auto Issue (브랜치명 → 이슈키 footer 자동 첨부)\n\n`sm config` → `autoIssue` 를 `on` 으로 설정하면 현재 브랜치명에서 이슈 키를 추출하여 commit 메시지 footer 에 `Refs:` 로 자동 첨부합니다.\n\n```bash\ngit checkout -b feature/AUTH-123-oauth-login\ngit add .\nsm c\n# →\n# feat(auth): add OAuth login flow\n#\n# - PKCE 기반 OAuth 콜백 처리 추가\n# ...\n#\n# Refs: AUTH-123\n```\n\n추출 패턴:\n- JIRA 류: `AUTH-123`, `PROJ-9999` 등 (대문자 prefix + 숫자)\n- GitHub 류: `#123`, `gh-123`, `issue-123`, `issue/123` 등\n\n### Fallback Provider\n\n`sm config` → `fallback` 에서 폴백 provider 를 등록하면, 메인 provider 가 실패 (503, timeout 등) 했을 때 자동으로 다른 provider 로 재시도합니다.\n\n```\nprovider : gemini    ← 메인\nfallback : groq      ← Gemini 503 시 자동으로 Groq 호출\n```\n\n두 provider 의 키가 모두 `sm login` 으로 등록되어 있어야 동작합니다.\n\n### Verbose / 디버그\n\n문제 진단이 필요할 때 `sm config` → `verbose` 를 `on` 으로 설정하면 prompt 와 응답이 stderr 에 출력됩니다. 환경변수로도 활성화 가능합니다.\n\n```bash\nSM_DEBUG=1 sm c\n```\n\n### Diff 마스킹 (자동)\n\n`.env` 류의 secret, AWS/GitHub 토큰, PEM private key 등은 AI 에 보내기 전 자동으로 `[REDACTED]` 로 마스킹됩니다. 사용자가 실수로 secret 을 staged 한 경우의 1차 방어선입니다.\n\n\u003e [!WARNING]\n\u003e 마스킹은 완전한 보호 수단이 아닙니다. secret 파일은 `.gitignore` 처리하는 것이 우선입니다.\n\n### On-failure (AI 호출 실패 시 동작)\n\n|  값        | 동작                                                           |\n| --------- | ------------------------------------------------------------ |\n| `fallback` (기본) | 안내 코멘트가 담긴 빈 템플릿을 적어 git 에디터가 열림. 사용자가 직접 메시지 작성 가능 |\n| `abort`   | 메시지를 비워둬 git 이 commit 자체를 취소                                 |\n\n`sm config` → `on-failure` 메뉴에서 변경 가능.\n\n\u003e [!NOTE]\n\u003e Gemini 의 503 (high demand), 일시 네트워크 단절 등으로 AI 메시지 생성이 실패하는 경우가 있습니다. 자동 재시도(429/5xx 대상, 백오프 0.6초·1.2초, 단일 호출 30초 타임아웃) + 폴백 provider (등록 시) 가 1차 방어선이며, 그래도 실패한 경우 위 옵션이 적용됩니다.\n\n### Custom Base URL (Azure OpenAI / 원격 Ollama 등)\n\n`sm config` → `baseUrl` 에서 OpenAI 호환 endpoint 또는 원격 Ollama 서버의 URL 을 지정할 수 있습니다.\n\n- OpenAI: Azure OpenAI, OpenRouter, 자체 호스팅 vLLM 등에 사용 (`https://your-resource.openai.azure.com/...`)\n- Ollama: 원격 머신에서 실행 중인 Ollama (`http://192.168.1.10:11434`)\n\n### 설정 변경\n\n```bash\nsm config\n```\n\n메뉴에서 변경할 항목을 선택합니다. provider 자체를 바꾸려면 `sm login` 을 다시 실행합니다 (다른 provider 의 키는 보존됩니다).\n\n\u003cbr\u003e\n\n---\n\n## 업데이트\n\n```bash\nsm update\n```\n\n`sm update` 를 실행하면 현재 버전과 npm registry 의 최신 버전을 비교한 뒤, 다른 경우에 한해 자동으로 `npm install -g smart-msg@latest` 를 수행합니다.\n\n수동으로 진행하시려면 다음과 동일합니다.\n\n```bash\nnpm install -g smart-msg@latest\n```\n\n### 버전 확인\n\n```bash\nsm --version       # 현재 버전만 출력\nsm status          # 현재 버전 + 최신 버전 비교 + 설정 정보 함께 출력\n```\n\n`sm status` 출력 예시:\n\n```text\nprovider : gemini\nmodel    : gemini-2.5-flash\nlanguage : ko\nstrength : middle\ntone     : report\ngitmoji  : off\nautoIssue: on\nfallback : groq\nonFail   : fallback\nverbose  : off\nconfig   : C:\\Users\\you\\.smart-msg\\config.json\nversion  : 1.1.54 → latest 1.2.0  ⇣  run `sm update` to upgrade\n```\n\n\u003e [!NOTE]\n\u003e 업데이트 후에도 기존 `~/.smart-msg/config.json` 의 설정과 API 키는 그대로 유지됩니다. 다시 로그인할 필요가 없습니다.\n\u003e\n\u003e 새로 추가된 provider (예: Ollama) 를 사용하려면 `sm login` 을 다시 실행하여 추가 키를 등록할 수 있습니다. 기존 키는 덮어쓰여지지 않습니다.\n\n\u003cbr\u003e\n\n---\n\n## 자동완성\n\n`sm \u003cTAB\u003e` 입력 시 서브커맨드(`login`, `logout`, `commit`, `pr`, `amend`, `split` 등) 가 자동으로 완성되도록 셸별 등록 스크립트를 제공합니다.\n\n### bash\n\n```bash\necho 'eval \"$(sm completion bash)\"' \u003e\u003e ~/.bashrc\nsource ~/.bashrc\n```\n\n### zsh\n\n```bash\necho 'eval \"$(sm completion zsh)\"' \u003e\u003e ~/.zshrc\nsource ~/.zshrc\n```\n\n### PowerShell\n\n```powershell\nsm completion powershell | Out-String | Invoke-Expression\n```\n\n영구 적용을 원하시는 경우 위 줄을 `$PROFILE` 파일에 추가합니다. (`notepad $PROFILE`)\n\n### clink (Windows cmd 사용자)\n\n`cmd.exe` 자체는 사용자 정의 자동완성을 지원하지 않습니다. [clink](https://chrisant996.github.io/clink) 를 설치하시면 cmd 위에서도 자동완성이 동작합니다.\n\n```cmd\nsm completion clink \u003e %LOCALAPPDATA%\\clink\\sm.lua\n```\n\n새 cmd 창부터 자동완성이 적용됩니다.\n\n\u003e [!NOTE]\n\u003e 순수 `cmd.exe` 는 자동완성을 지원하지 않습니다. PowerShell 또는 clink 를 사용하시기 바랍니다.\n\n\u003cbr\u003e\n\n---\n\n## 지원 환경\n\n`smart-msg` 는 git 명령이 동작하는 모든 환경에서 동일하게 사용할 수 있습니다.\n\n### 터미널\n\nGit Bash, PowerShell, Windows CMD, macOS Terminal, iTerm2, Linux Bash / Zsh 모두 별도 설정 없이 동작합니다.\n\n\u003e [!NOTE]\n\u003e PowerShell 에서 `sm` 실행이 차단되는 경우 다음 명령으로 정책을 완화합니다.\n\u003e ```powershell\n\u003e Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned\n\u003e ```\n\n### IDE\n\n| IDE | 사용 방법 |\n| --- | --- |\n| IntelliJ IDEA / WebStorm / PyCharm | `Ctrl + K` 로 커밋 창을 열면 메시지가 자동으로 채워집니다 |\n| VS Code, Cursor | `Ctrl + Shift + G` 로 Source Control 패널을 열고 commit 시 메시지가 자동으로 채워집니다 |\n| 그 외 IDE | 내장 터미널이 있는 모든 IDE 에서 동일하게 동작합니다 |\n\n\u003e [!TIP]\n\u003e IDE 커밋 창 통합은 `sm login` 의 마지막 단계에서 글로벌 hook 을 설치한 경우에만 동작합니다. 설치하지 않은 경우 `sm login` 을 다시 실행하여 활성화할 수 있습니다.\n\n### 비 Node.js 프로젝트\n\n`smart-msg` 는 글로벌 CLI 이므로 프로젝트 언어와 무관하게 동작합니다. Java, Python, Go 등 어떤 언어 프로젝트에서도 동일하게 사용할 수 있으며, `node_modules` 폴더가 프로젝트에 생성되지 않습니다.\n\n\u003cbr\u003e\n\n---\n\n## 제거\n\n```bash\nsm uninstall\nnpm uninstall -g smart-msg\n```\n\n`sm uninstall` 이 다음 항목을 모두 정리합니다.\n\n- 설정 디렉토리 (`~/.smart-msg/`)\n- 글로벌 git hook 설정 (이전 값이 있다면 복원)\n- 프로젝트별 설치된 hook (있는 경우)\n\n이후 `npm uninstall -g smart-msg` 로 패키지 본체를 제거하면 완전히 정리됩니다.\n\n\u003e [!WARNING]\n\u003e npm 은 글로벌 패키지 uninstall 시 lifecycle script 의 실행을 차단합니다. `sm uninstall` 을 먼저 실행하지 않으면 `~/.smart-msg/` 가 그대로 남아 API 키도 보존됩니다.\n\n\u003cbr\u003e\n\n---\n\n## License\n\nISC\n\n\u003cbr\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003csub\u003eBuilt with TypeScript \u0026nbsp;·\u0026nbsp; Powered by Google Gemini, Groq, OpenAI, Anthropic Claude \u0026amp; Ollama\u003c/sub\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblack-astro%2Fsmart-msg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblack-astro%2Fsmart-msg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblack-astro%2Fsmart-msg/lists"}