commit-ai-agent 1.0.7 → 1.0.9

package/README.md

@@ -2,6 +2,27 @@
 
 AI가 git 커밋과 현재 변경사항을 한국어로 자동 분석해주는 개발자 도구입니다.
 
+---
+
+## CLI AI와 무엇이 다른가요?
+
+Claude Code나 Codex 같은 CLI AI가 있는데 왜 commit-ai-agent를 써야 할까요?
+
+| 기능 | CLI AI (Claude Code / Codex) | commit-ai-agent |
+| ---- | :--------------------------: | :-------------: |
+| 커밋 분석 | 수동 명령어 입력 필요 | **자동** (git commit 직후 백그라운드 실행) |
+| 분석 범위 | 현재 세션 단일 프로젝트 | 현재 프로젝트 자동 분석 |
+| 상시 실행 | 세션 종료 시 중단 | **데몬 서버** — 항상 켜져 있음 |
+| Secret 탐지 | 없음 | **pre-push 훅** — push 전 자격증명 자동 차단 |
+| 오프라인 큐 | 없음 | 서버 꺼진 동안 커밋 → 재시작 시 **자동 처리** |
+| 분석 UI | 터미널 텍스트 | **브라우저 GUI** — 검색·필터·저장 |
+| AI 비용 | 구독료 or API 종량제 | Google Gemini **무료 티어** 지원 |
+| 개인화 | 없음 | 프로젝트별 리포트를 `reports/`에 **자동 저장** |
+
+> commit-ai-agent의 핵심 가치: **"커밋하면 알아서 분석된다"** — 개발자는 코드에만 집중하세요.
+
+---
+
 ## 요구 사항
 
 - [Node.js](https://nodejs.org) 18 이상
@@ -14,7 +35,7 @@ AI가 git 커밋과 현재 변경사항을 한국어로 자동 분석해주는
 
 ### 방법 A — npx (설치 없이 바로 실행)
 
-- 프로젝트가 모여있는 디렉토리 or 프로젝트 루트에서 명령어 실행
+- 프로젝트 루트에서 명령어 실행
 - 해당 디렉토리에서 .env 파일 생성(.env.example 참고)
 
 ```bash
@@ -24,7 +45,7 @@ npx commit-ai-agent
 ### 방법 B — 전역 설치 후 명령어로 실행
 
 - 전역으로 설치하면 어느 위치에서든 `commit-ai-agent` 명령어로 실행 가능
-- 프로젝트가 모여있는 디렉토리 or 프로젝트 루트에서 명령어 실행
+- 프로젝트 루트에서 명령어 실행
 - 해당 디렉토리에서 .env 파일 생성(.env.example 참고)
 
 ```bash
@@ -34,8 +55,6 @@ commit-ai-agent
 
 ### 방법 C — 직접 클론
 
-프로젝트가 모여있는 디렉토리에 클론한 후, 해당 디렉토리에서 명령어 실행
-
 ```bash
 git clone https://github.com/cjy3458/commit-ai-agent.git
 cd commit-ai-agent
@@ -83,13 +102,103 @@ DEV_ROOT=C:/Users/projects => 선택 사항(미설정 시 현재 실행 디렉
 
 ---
 
+## 새 기능 사용법
+
+### Git Hook 자동화 — 커밋 후 자동 분석
+
+서버가 실행 중인 상태에서 git hook을 설치하면, `git commit` 직후 자동으로 분석이 시작됩니다.
+
+> hook은 **현재 디렉토리(CWD)** 프로젝트에만 설치됩니다. hook을 설치할 프로젝트 안에서 명령어를 실행하세요.
+
+#### 1. Hook 설치
+
+```bash
+# 현재 디렉토리 프로젝트에 설치
+commit-ai-agent hook install
+```
+
+#### 2. Hook 상태 확인
+
+```bash
+commit-ai-agent hook status
+```
+
+```
+  훅 설치 상태:
+  ──────────────────────────────────────────────────
+  my-app                   post-commit: ✅  pre-push: ✅
+```
+
+#### 3. Hook 제거
+
+```bash
+commit-ai-agent hook remove
+```
+
+#### 4. 동작 방식
+
+```
+git commit
+   ↓
+post-commit hook 실행
+   ├── 서버가 켜져 있음 → 즉시 분석 시작 (브라우저 UI에서 확인)
+   └── 서버가 꺼져 있음 → 조용히 종료 (분석 생략)
+```
+
+> Hook은 기존 `.git/hooks/post-commit`이 있어도 안전하게 추가됩니다 (기존 내용 유지).
+
+---
+
+### Secret 유출 탐지 — push 전 자동 차단
+
+`pre-push` hook이 설치되어 있으면 `git push` 전에 변경 파일을 자동 스캔합니다.
+실제 자격증명이 감지되면 push가 차단되고 위치와 유형을 알려줍니다.
+
+#### 탐지 패턴
+
+| 유형 | 심각도 |
+| ---- | ------ |
+| AWS Access Key (`AKIA...`) | Critical |
+| Google API Key (`AIza...`) | Critical |
+| GitHub Personal Token (`ghp_...`) | Critical |
+| Slack Token (`xox...`) | Critical |
+| Stripe Secret Key (`sk_live_...`) | Critical |
+| JWT Token | High |
+| Private Key PEM | Critical |
+| 패스워드 직접 할당 | Medium |
+| API Key 직접 할당 | Medium |
+
+#### 차단 메시지 예시
+
+```
+╔══════════════════════════════════════════════════════╗
+║  ⛔  commit-ai-agent: SECRET DETECTED                ║
+╚══════════════════════════════════════════════════════╝
+
+push가 차단됐습니다. 아래 항목을 확인하세요:
+
+  1. 파일: src/config.js:12 [CRITICAL]
+     유형: Google API Key
+     값:   AIza****y8Xw
+```
+
+#### 오탐(false positive)인 경우 우회
+
+```bash
+SKIP_SECRET_SCAN=1 git push
+```
+
+> Gemini API 키가 설정되어 있으면 AI가 오탐 여부를 자동으로 검증하여 불필요한 차단을 줄입니다.
+
+---
+
 ## 문제 해결
 
 **429 오류 (할당량 초과)**
 → Gemini 무료 티어 한도 도달. 잠시 후 재시도하거나 [유료 플랜](https://ai.google.dev)으로 업그레이드하세요.
 
 **프로젝트 목록이 안 뜸**
-→ 기본값은 실행 디렉토리입니다. 필요 시 `DEV_ROOT`를 git 저장소가 모인 상위 폴더로 지정하세요.
+→ 기본값은 실행 디렉토리입니다. `DEV_ROOT` 환경변수로 프로젝트 경로를 직접 지정할 수 있습니다.
 
 **`[DEP0190] DeprecationWarning` 경고 (Node.js 22+)**
 → `shell: true` 옵션과 args 배열을 함께 전달할 때 Node.js 22 이상에서 발생하는 보안 경고입니다. v1.0.7 이상으로 업데이트하면 해결됩니다.
@@ -142,24 +251,31 @@ git checkout -b feat/my-feature
 ## 프로젝트 구조
 
 ```
-commit-analyzer/
+commit-ai-agent/
 ├── bin/
-│   └── cli.js          # CLI 진입점 (npx / npm install -g)
+│   └── cli.js              # CLI 진입점 (npx / npm install -g)
 ├── src/
-│   ├── server.js       # Express 서버 · API 라우트 · SSE 스트리밍
-│   ├── analyzer.js     # Gemini AI 분석 프롬프트 · 재시도 로직
-│   └── git.js          # simple-git 래퍼 (커밋 조회, status diff)
-├── public/             # 프론트엔드 정적 파일 (HTML · CSS · JS)
-├── .env.example        # 환경변수 예시
+│   ├── server.js           # Express 서버 · API 라우트 · SSE 스트리밍
+│   ├── analyzer.js         # Gemini AI 분석 프롬프트 · 재시도 로직
+│   ├── git.js              # simple-git 래퍼 (커밋 조회, status diff)
+│   └── hooks/
+│       ├── installer.js    # git hook 설치·제거·상태 확인
+│       ├── post-commit.js  # post-commit 훅 스크립트 (자동 분석 트리거)
+│       └── pre-push.js     # pre-push 훅 스크립트 (Secret 탐지)
+├── public/                 # 프론트엔드 정적 파일 (HTML · CSS · JS)
+├── .env.example            # 환경변수 예시
 └── package.json
 ```
 
-| 파일              | 역할                                                  |
-| ----------------- | ----------------------------------------------------- |
-| `bin/cli.js`      | npx 실행 시 .env 로드, 브라우저 자동 오픈, 서버 시작  |
-| `src/server.js`   | REST API + SSE 엔드포인트, 리포트 저장                |
-| `src/analyzer.js` | Gemini API 호출, 모델 폴백(2.5→2.0→lite), 지수 백오프 |
-| `src/git.js`      | 프로젝트 목록 탐색, 커밋 diff, working status diff    |
+| 파일                      | 역할                                                          |
+| ------------------------- | ------------------------------------------------------------- |
+| `bin/cli.js`              | npx 실행, hook 서브커맨드 (install / remove / status)         |
+| `src/server.js`           | REST API + SSE 엔드포인트, 리포트 저장                        |
+| `src/analyzer.js`         | Gemini API 호출, 모델 폴백(2.5→2.0→lite), 지수 백오프         |
+| `src/git.js`              | 프로젝트 목록 탐색, 커밋 diff, working status diff            |
+| `src/hooks/installer.js`  | git hook 스크립트 설치·제거 (기존 hook 보존)                  |
+| `src/hooks/post-commit.js`| 커밋 직후 서버 알림 (서버 없으면 조용히 종료)                 |
+| `src/hooks/pre-push.js`   | push 전 15가지 패턴으로 Secret 스캔, Gemini AI 오탐 필터링    |
 
 ---
 

package/bin/cli.js

@@ -2,6 +2,12 @@
 /**
  * commit-ai-agent CLI 진입점
  * npx commit-ai-agent 또는 npm install -g 후 commit-ai-agent 명령으로 실행
+ *
+ * 서브커맨드:
+ *   (없음)           웹 UI 서버 실행
+ *   hook install     현재 디렉토리에 git hook 설치
+ *   hook remove      git hook 제거
+ *   hook status      git hook 설치 상태 확인
  */
 import dotenv from "dotenv";
 import path from "path";
@@ -11,10 +17,100 @@ import { spawn } from "child_process";
 // 사용자 현재 디렉토리의 .env 로드
 dotenv.config({ path: path.resolve(process.cwd(), ".env") });
 
-// 패키지 루트 경로를 환경변수로 전달 (server.js가 public/ 위치를 찾기 위함)
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// 패키지 루트 경로를 환경변수로 전달 (server.js가 public/ 위치를 찾기 위함)
 process.env.COMMIT_ANALYZER_ROOT = path.resolve(__dirname, "..");
 
+const [, , subCmd, ...subArgs] = process.argv;
+
+// ──────────────────────────────────────────────
+//  hook 서브커맨드
+// ──────────────────────────────────────────────
+if (subCmd === "hook") {
+  const action = subArgs[0]; // install | remove | status
+  const { installHooks, removeHooks, getHookStatus } = await import(
+    "../src/hooks/installer.js"
+  );
+
+  function resolveTargets() {
+    return [process.cwd()];
+  }
+
+  if (action === "install") {
+    const targets = await resolveTargets();
+    console.log("");
+    for (const target of targets) {
+      try {
+        const installed = await installHooks(target);
+        console.log(
+          `  ✅ 설치됨: ${path.basename(target)} (${installed.join(", ")})`
+        );
+      } catch (err) {
+        console.error(`  ❌ 실패: ${path.basename(target)} — ${err.message}`);
+      }
+    }
+    console.log("");
+    console.log("  이제 커밋할 때마다 자동으로 분석됩니다.");
+    console.log("  push 전에 secret 유출도 자동으로 검사됩니다.");
+    console.log("");
+    process.exit(0);
+  }
+
+  if (action === "remove") {
+    const targets = await resolveTargets();
+    console.log("");
+    for (const target of targets) {
+      try {
+        const removed = await removeHooks(target);
+        if (removed.length > 0) {
+          console.log(
+            `  ✅ 제거됨: ${path.basename(target)} (${removed.join(", ")})`
+          );
+        } else {
+          console.log(`  ℹ️  훅 없음: ${path.basename(target)}`);
+        }
+      } catch (err) {
+        console.error(`  ❌ 실패: ${path.basename(target)} — ${err.message}`);
+      }
+    }
+    console.log("");
+    process.exit(0);
+  }
+
+  if (action === "status") {
+    const targets = await resolveTargets();
+    console.log("");
+    console.log("  훅 설치 상태:");
+    console.log("  " + "─".repeat(50));
+    for (const target of targets) {
+      try {
+        const status = await getHookStatus(target);
+        const pc = status.postCommit.installed ? "✅" : "❌";
+        const pp = status.prePush.installed ? "✅" : "❌";
+        console.log(
+          `  ${path.basename(target).padEnd(24)} post-commit: ${pc}  pre-push: ${pp}`
+        );
+      } catch (err) {
+        console.error(`  ❌ 오류: ${path.basename(target)} — ${err.message}`);
+      }
+    }
+    console.log("");
+    process.exit(0);
+  }
+
+  // 알 수 없는 action
+  console.log("");
+  console.log("  사용법:");
+  console.log("    commit-ai-agent hook install   # 현재 디렉토리에 훅 설치");
+  console.log("    commit-ai-agent hook remove    # 훅 제거");
+  console.log("    commit-ai-agent hook status    # 상태 확인");
+  console.log("");
+  process.exit(1);
+}
+
+// ──────────────────────────────────────────────
+//  기본 동작: 웹 UI 서버 실행
+// ──────────────────────────────────────────────
 const PORT = process.env.PORT || 3000;
 
 console.log("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commit-ai-agent",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "AI-powered git commit & working status analyzer with web UI",
   "type": "module",
   "main": "src/server.js",

package/public/app.js

@@ -78,6 +78,9 @@ async function init() {
     setAriaState("idle");
   }
 
+  // SSE: post-commit 자동 분석 이벤트 수신
+  connectAutoAnalysisEvents();
+
   // wire static event listeners (elements guaranteed to exist now)
   document
     .getElementById("refresh-projects")
@@ -97,6 +100,9 @@ async function init() {
     .addEventListener("click", () => {
       togglePre("status-diff-content", "status-diff-toggle-btn");
     });
+  document
+    .getElementById("refresh-hooks")
+    .addEventListener("click", loadHookStatus);
 }
 
 // ── Config check ──
@@ -116,26 +122,27 @@ async function checkConfig() {
 
 // ── Single Project Mode ──
 async function enterSingleProjectMode() {
-  // 프로젝트 선택 UI 숨김
+  // 프로젝트 선택 UI만 숨김 (모드 토글은 유지)
   const header = document.querySelector(".selector-card .card-header");
-  const modeToggle = document.querySelector(".mode-toggle");
   const projectGrid = document.getElementById("project-grid");
   const selectedHint = document.getElementById("selected-hint");
   if (header) header.style.display = "none";
-  if (modeToggle) modeToggle.style.display = "none";
   if (projectGrid) projectGrid.style.display = "none";
   if (selectedHint) selectedHint.style.display = "none";
 
   // 현재 디렉토리를 프로젝트로 자동 선택
   selectedProject = "__self__";
-  analyzeMode = "status";
 
   document.getElementById("analyze-btn").disabled = false;
   const btnText = document.getElementById("analyze-btn-text");
-  if (btnText) btnText.textContent = "Hanni에게 리뷰 요청";
+  if (btnText) btnText.textContent = "Hanni에게 분석 요청";
 
-  // 변경사항 미리 로드
-  await fetchStatusPreview();
+  // 현재 모드에 따라 미리 로드
+  if (analyzeMode === "commit") {
+    await fetchCommitPreview();
+  } else {
+    await fetchStatusPreview();
+  }
 }
 
 // ── Projects ──
@@ -439,6 +446,100 @@ function onCopy() {
   });
 }
 
+// ── Auto Analysis via SSE (+ polling fallback) ──
+let autoAnalysisPollTimer = null;
+let autoAnalysisShownFilename = null; // 이미 표시한 리포트 중복 방지
+
+function connectAutoAnalysisEvents() {
+  const evtSource = new EventSource("/api/events");
+
+  evtSource.onmessage = (e) => {
+    try {
+      const data = JSON.parse(e.data);
+      handleAutoAnalysisEvent(data);
+    } catch {}
+  };
+
+  evtSource.onerror = () => {
+    // EventSource 자동 재연결됨 — 별도 처리 불필요
+  };
+
+  // SSE와 관계없이 5초마다 상태 폴링 (SSE 놓쳐도 반드시 동작)
+  startAutoAnalysisPoll();
+}
+
+function handleAutoAnalysisEvent(data) {
+  if (isAnalyzing) return; // 수동 분석 중엔 방해 안 함
+  if (data.type === "analysis-started") {
+    showAutoAnalysisStarted(data.projectName);
+    startAutoAnalysisPoll(); // SSE가 끊겨도 완료를 폴링으로 감지
+  } else if (data.type === "analysis-done") {
+    stopAutoAnalysisPoll();
+    if (data.filename !== autoAnalysisShownFilename) {
+      autoAnalysisShownFilename = data.filename;
+      showAutoAnalysisDone(data);
+    }
+  } else if (data.type === "analysis-error") {
+    stopAutoAnalysisPoll();
+    setStatus("error", `자동 분석 오류: ${data.message}`);
+    setAriaState("error");
+  }
+}
+
+// 5초마다 서버 상태 폴링 (SSE 대비 폴백)
+function startAutoAnalysisPoll() {
+  stopAutoAnalysisPoll();
+  autoAnalysisPollTimer = setInterval(async () => {
+    if (isAnalyzing) return;
+    try {
+      const res = await fetch("/api/auto-analysis/state");
+      const state = await res.json();
+      if (state.status === "analyzing" && autoAnalysisShownFilename !== "__loading__") {
+        autoAnalysisShownFilename = "__loading__";
+        showAutoAnalysisStarted(state.projectName);
+      } else if (state.status === "done" && state.filename !== autoAnalysisShownFilename) {
+        autoAnalysisShownFilename = state.filename;
+        showAutoAnalysisDone(state);
+      }
+    } catch {}
+  }, 5000);
+}
+
+function stopAutoAnalysisPoll() {
+  if (autoAnalysisPollTimer) {
+    clearInterval(autoAnalysisPollTimer);
+    autoAnalysisPollTimer = null;
+  }
+}
+
+function showAutoAnalysisStarted(projectName) {
+  const resultCard = document.getElementById("result-card");
+  const analysisBody = document.getElementById("analysis-body");
+  const reportSaved = document.getElementById("report-saved");
+  resultCard.style.display = "block";
+  analysisBody.innerHTML = "";
+  reportSaved.textContent = "";
+  document.getElementById("copy-btn").style.display = "none";
+  setStatus("loading", `${projectName} 커밋 자동 분석 중...`);
+  setAriaState("thinking");
+  resultCard.scrollIntoView({ behavior: "smooth", block: "start" });
+}
+
+function showAutoAnalysisDone({ filename, content }) {
+  const resultCard = document.getElementById("result-card");
+  const analysisBody = document.getElementById("analysis-body");
+  const reportSaved = document.getElementById("report-saved");
+  const copyBtn = document.getElementById("copy-btn");
+  resultCard.style.display = "block"; // ← 핵심: 카드 표시
+  analysisBody.innerHTML = marked.parse(content);
+  reportSaved.textContent = `✓ 저장됨: ${filename}`;
+  setStatus("done", "✅ 자동 분석 완료!");
+  setAriaState("done");
+  copyBtn.style.display = "inline-flex";
+  copyBtn._text = content;
+  resultCard.scrollIntoView({ behavior: "smooth", block: "start" });
+}
+
 // ── Reports Tab ──
 async function loadReports() {
   const listEl = document.getElementById("reports-list");
@@ -505,10 +606,85 @@ function setupTabs() {
       btn.classList.add("active");
       document.getElementById("tab-" + tab).classList.add("active");
       if (tab === "reports") loadReports();
+      if (tab === "hooks") loadHookStatus();
     });
   });
 }
 
+// ── Hooks Tab ──
+async function loadHookStatus() {
+  const listEl = document.getElementById("hook-projects-list");
+  listEl.innerHTML = '<p class="empty-state">불러오는 중...</p>';
+  try {
+    const res = await fetch("/api/hooks/status");
+    const { projects } = await res.json();
+    if (!projects || projects.length === 0) {
+      listEl.innerHTML =
+        '<p class="empty-state">git 프로젝트를 찾을 수 없습니다.</p>';
+      return;
+    }
+    listEl.innerHTML = projects
+      .map((p) => {
+        const pcInstalled = p.postCommit?.installed;
+        const ppInstalled = p.prePush?.installed;
+        const allInstalled = pcInstalled && ppInstalled;
+        const noneInstalled = !pcInstalled && !ppInstalled;
+        const statusBadge = allInstalled
+          ? '<span class="hook-badge installed">설치됨</span>'
+          : noneInstalled
+            ? '<span class="hook-badge not-installed">미설치</span>'
+            : '<span class="hook-badge partial">일부 설치</span>';
+
+        const displayName = p.displayName || p.name;
+        return `<div class="hook-project-row" data-name="${escHtml(p.name)}">
+          <div class="hook-project-info">
+            <span class="hook-project-name">${escHtml(displayName)}</span>
+            ${statusBadge}
+            <span class="hook-detail">post-commit: ${pcInstalled ? "✅" : "❌"} &nbsp; pre-push: ${ppInstalled ? "✅" : "❌"}</span>
+          </div>
+          <div class="hook-project-actions">
+            ${
+              allInstalled
+                ? `<button class="btn-ghost hook-remove-btn" data-name="${escHtml(p.name)}">제거</button>`
+                : `<button class="btn-secondary hook-install-btn" data-name="${escHtml(p.name)}">설치</button>`
+            }
+          </div>
+        </div>`;
+      })
+      .join("");
+
+    listEl.querySelectorAll(".hook-install-btn").forEach((btn) => {
+      btn.addEventListener("click", () => handleHookAction("install", btn.dataset.name, btn));
+    });
+    listEl.querySelectorAll(".hook-remove-btn").forEach((btn) => {
+      btn.addEventListener("click", () => handleHookAction("remove", btn.dataset.name, btn));
+    });
+  } catch {
+    listEl.innerHTML =
+      '<p class="empty-state" style="color:var(--danger)">훅 상태를 불러오지 못했습니다.</p>';
+  }
+}
+
+async function handleHookAction(action, projectName, btn) {
+  const original = btn.textContent;
+  btn.disabled = true;
+  btn.textContent = action === "install" ? "설치 중..." : "제거 중...";
+  try {
+    const res = await fetch(`/api/hooks/${action}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ projectName }),
+    });
+    const data = await res.json();
+    if (!res.ok) throw new Error(data.error || "요청 실패");
+    await loadHookStatus(); // 새로고침
+  } catch (err) {
+    btn.disabled = false;
+    btn.textContent = original;
+    alert(`오류: ${err.message}`);
+  }
+}
+
 // ── Helpers ──
 function togglePre(preId, btnId) {
   const pre = document.getElementById(preId);

package/public/index.html

@@ -21,7 +21,6 @@
     <link rel="stylesheet" href="/style.css" />
   </head>
   <body>
-    <!-- ── Header ── -->
     <header class="header">
       <div class="header-inner">
         <div class="logo">
@@ -36,6 +35,9 @@
           <button class="nav-btn" data-tab="reports" id="btn-reports">
             리포트
           </button>
+          <button class="nav-btn" data-tab="hooks" id="btn-hooks">
+            훅 관리
+          </button>
         </nav>
         <div class="aria-chip" id="aria-chip">
           <span class="aria-chip-dot" id="aria-chip-dot"></span>
@@ -44,11 +46,8 @@
       </div>
     </header>
 
-    <!-- ── Main ── -->
     <main class="main">
-      <!-- ── Tab: Analyze ── -->
       <section class="tab-content active" id="tab-analyze">
-        <!-- ── Aria Hero ── -->
         <div class="aria-hero">
           <div class="aria-robot-wrap idle" id="aria-robot-wrap">
             <svg
@@ -80,7 +79,6 @@
                   <stop offset="100%" stop-color="#0e7490" />
                 </linearGradient>
               </defs>
-              <!-- Antenna -->
               <line
                 x1="45"
                 y1="7"
@@ -265,6 +263,71 @@
         </div>
       </section>
 
+      <!-- ── Tab: Hooks ── -->
+      <section class="tab-content" id="tab-hooks">
+        <div class="card">
+          <div class="card-header">
+            <h2 class="card-title">🪝 Git Hook 관리</h2>
+            <button class="btn-ghost" id="refresh-hooks" title="새로고침">
+              ↻
+            </button>
+          </div>
+          <p class="hook-desc">
+            훅을 설치하면 <strong>커밋할 때마다 자동으로 AI 분석</strong>이
+            실행되고, <strong>push 전에 secret 유출을 자동 차단</strong>합니다.
+          </p>
+
+          <div class="hook-section">
+            <div class="hook-section-title">
+              <span class="hook-icon">⚡</span>
+              post-commit — 자동 커밋 분석
+            </div>
+            <p class="hook-section-desc">
+              커밋 직후 Gemini AI가 백그라운드에서 분석 리포트를 자동
+              생성합니다.
+            </p>
+          </div>
+
+          <div class="hook-section">
+            <div class="hook-section-title">
+              <span class="hook-icon">⛔</span>
+              pre-push — Secret 유출 탐지
+            </div>
+            <p class="hook-section-desc">
+              push 전에 API 키, 비밀번호, private key 등의 유출을 탐지하고
+              차단합니다.
+            </p>
+          </div>
+
+          <div id="hook-projects-list" class="hook-projects-list">
+            <p class="empty-state">불러오는 중...</p>
+          </div>
+        </div>
+
+        <div class="card hook-cli-card">
+          <h2 class="card-title">💻 CLI 사용법</h2>
+          <div class="hook-cli-block">
+            <div class="hook-cli-item">
+              <code>commit-ai-agent hook install</code>
+              <span>현재 디렉토리에 훅 설치</span>
+            </div>
+
+            <div class="hook-cli-item">
+              <code>commit-ai-agent hook remove</code>
+              <span>훅 제거</span>
+            </div>
+            <div class="hook-cli-item">
+              <code>commit-ai-agent hook status</code>
+              <span>설치 상태 확인</span>
+            </div>
+            <div class="hook-cli-item">
+              <code>SKIP_SECRET_SCAN=1 git push</code>
+              <span>Secret 스캔 일시 스킵 (오탐 시)</span>
+            </div>
+          </div>
+        </div>
+      </section>
+
       <!-- ── Tab: Reports ── -->
       <section class="tab-content" id="tab-reports">
         <div class="card">