shellbase 0.8.0 → 0.9.0

package/README.md

@@ -36,7 +36,40 @@ shellbase start --dir ~/projects/my-app --name "내 노트북"
 | `shellbase login` | 구글 계정으로 로그인 |
 | `shellbase logout` | 로그아웃 |
 | `shellbase whoami` | 현재 로그인된 계정 확인 |
-| `shellbase start [--dir <path>] [--name <name>] [--require-approval] [--no-restore]` | 터미널 세션 시작 |
+| `shellbase start [--dir <path>] [--name <name>] [--require-approval] [--no-restore] [--no-hook]` | 터미널 세션 시작 |
+| `shellbase hook install` / `remove` / `status` | Claude Code 작업 완료 알림 켜기/끄기/확인 |
+| `shellbase notify` | "작업이 끝났다"고 폰에 알림 (Claude Code 훅이 자동 실행 — 직접 칠 일은 없어요) |
+
+### 작업이 끝나면 폰으로 알려줘요
+
+Claude Code 에게 긴 작업을 시켜놓고 폰을 내려놓아도, **끝나면 알 수 있어요.**
+
+- 폰·PC 의 **세션 목록과 상단 칩에 주황 점(●)** 이 붙어요 — 그 세션에 들어가 보면 사라집니다
+- 앱을 열어둔 상태라면 **알림창**도 띄울 수 있어요 (명령창 `Ctrl+Shift+P` → "작업 완료 알림 켜기")
+- 앱을 아예 닫아둔 사이에 끝난 작업도 **●** 로 남아 있어서, 나중에 열어보면 바로 보여요
+
+끝난 걸 알아채는 방법은 두 가지고, 정확한 쪽이 우선입니다.
+
+| 방법 | 정확도 | 준비 |
+|---|---|---|
+| **Claude Code 훅** | 정확 (Claude 가 대답을 마치는 바로 그 순간) | `shellbase hook install` 한 번 |
+| 화면 출력 보고 짐작 | 어림짐작 | 없음 (훅이 없을 때 자동으로 대신 씀) |
+
+`shellbase start` 를 처음 실행하면 훅을 걸지 한 번 물어봐요. `y` 를 누르면
+`~/.claude/settings.json` 에 알림 한 줄이 들어갑니다 — **원래 있던 설정은 그대로 두고**, 고치기 전
+같은 자리에 `settings.json.shellbase-backup` 으로 백업도 남겨요. 이미 켜져 있던 Claude Code 는 다시
+시작해야 적용돼요.
+
+```bash
+shellbase hook status     # 지금 걸려 있는지 확인
+shellbase hook install    # 걸기
+shellbase hook remove     # 빼기 (다른 설정은 안 건드려요)
+shellbase start --no-hook # 물어보지 않고 시작
+```
+
+훅이 없을 때 쓰는 짐작 방식은 "한동안 화면이 쉼 없이 바쁘다가(3초 이상, 글자 2KB 이상) 갑자기
+4초간 조용해지면 끝난 것" 으로 봅니다. 그래서 `ls` 처럼 짧은 명령이나 타이핑에는 반응하지 않지만,
+Claude Code 가 아닌 긴 명령(빌드 등)이 끝나도 알림이 올 수 있어요.
 
 ### 접속 승인 정책
 
@@ -130,17 +163,26 @@ shellbase start --no-restore     # 복구하지 않고 이 폴더 세션 하나
 
 ### 폰에서 마이크로 말하기 (음성 → 글자)
 
-폰 화면 오른쪽 아래 **마이크 버튼**을 누르고 말하면, 녹음이 **이 컴퓨터로** 전송돼서 컴퓨터에 떠 있는
-음성인식 서버가 글자로 바꿔줍니다. 기본값은 **말한 뒤 바로 보내기(엔터까지 자동)** 라서, 「완료」만
-누르면 그대로 실행돼요 (Claude Code 에게 말로 시킬 때 편합니다). 확인하고 보내고 싶으면 명령창의
-`말한 뒤 바로 보내기 끄기` 로 예전 방식(받아쓴 글자를 보여주고 `보내기 ↵` 를 누르는 방식)으로 바꿀 수 있어요.
+폰 화면 오른쪽 아래 **마이크 버튼**을 누르고 말하면 글자로 바뀝니다. 기본값은 **말한 뒤 바로
+보내기(엔터까지 자동)** 라서, 「완료」만 누르면 그대로 실행돼요 (Claude Code 에게 말로 시킬 때
+편합니다). 확인하고 보내고 싶으면 명령창의 `말한 뒤 바로 보내기 끄기` 로 예전 방식(받아쓴 글자를
+보여주고 `보내기 ↵` 를 누르는 방식)으로 바꿀 수 있어요.
+
+**받아쓰는 곳은 두 군데고, 준비된 쪽이 자동으로 쓰입니다.** 폰 화면에 어느 쪽인지 표시돼요.
+
+| | 내 컴퓨터에서 받아쓰기 | 브라우저가 받아쓰기 |
+|---|---|---|
+| 언제 | 이 컴퓨터에 음성인식 서버가 떠 있을 때 | 그 밖의 모든 경우 |
+| 준비 | 서버를 직접 띄워야 함 | **필요 없음** |
+| 목소리가 나가는 곳 | 안 나감 (내 컴퓨터에서 끝) | 브라우저 회사 서버 (크롬=구글, 사파리=애플) |
+| 품질 | 좋음 | 보통 |
 
-- **녹음은 다른 회사 서버로 나가지 않아요** — 폰 → (암호화된 실시간 채널) → 내 컴퓨터 → 내 음성인식 서버
 - 음성인식 서버는 시작할 때 자동으로 찾아요: `SHELLBASE_STT_URL` → `http://127.0.0.1:5005`
   → `http://172.17.0.1:5005`(도커 안에서 본 호스트) 순서
 - 주소가 다르면 `SHELLBASE_STT_URL=http://127.0.0.1:9000` 처럼 지정하고 다시 시작하세요.
   인식 언어는 `SHELLBASE_STT_LANGS=ko,en` 으로 바꿀 수 있어요 (기본 `ko`)
-- 서버가 없으면 마이크 기능만 꺼지고 나머지는 그대로 동작해요 (시작할 때 로그로 알려줍니다)
+- 일부러 브라우저 쪽을 쓰고 싶으면(또는 5005 포트를 다른 프로그램이 쓰고 있으면)
+  `shellbase start --no-stt` 또는 `SHELLBASE_NO_STT=1`
 - 필요한 서버 형식: `GET /health` 와 `POST /transcribe_json` (`{audio_base64, languages}` → `{ok, text}`) —
   whisper 계열 서버면 대개 이 형태입니다
 
@@ -155,6 +197,9 @@ shellbase start --no-restore     # 복구하지 않고 이 폴더 세션 하나
 - `node-pty` 를 사용해서 설치 시 네이티브 모듈을 컴파일합니다. macOS는 Xcode Command Line Tools,
   Linux는 `build-essential`(또는 배포판의 동급 패키지), Windows는 Visual Studio Build Tools가
   필요할 수 있어요.
+- 폰이 (재)접속하면 **지금 화면 그대로** 복원돼요. 에이전트가 화면 상태를 따로 들고 있다가 그대로
+  보내주기 때문에, Claude Code 같은 전체화면 앱을 보다가 잠깐 끊겼다 돌아와도 화면이 깨지지 않아요
+  (이전 300줄까지 함께 복원).
 - 터미널 내용은 기기별 키로 암호화돼서 전송되고, 모바일에서 접속을 시도할 때마다 데스크톱에서
   직접 승인해야 입력이 가능합니다.
 

package/dist/agent.js

@@ -9,10 +9,10 @@ import { SerializeAddon } from '@xterm/addon-serialize';
 const requireCjs = createRequire(import.meta.url);
 const { Terminal: HeadlessTerminal } = requireCjs('@xterm/headless');
 import { requireClient } from './auth.js';
-import { TERMINAL_CATEGORY, CONTROL_TOKEN } from './config.js';
+import { TERMINAL_CATEGORY, CONTROL_TOKEN, SESSION_ENV } from './config.js';
 import { startSleepGuard, stopSleepGuard } from './sleep-guard.js';
 import { encryptFrame, decryptFrame, generateFrameKey } from './crypto.js';
-import { registerDevice, heartbeatDevice, unregisterDevice, listOnlineNames, renameDevice, } from './devices.js';
+import { registerDevice, heartbeatDevice, unregisterDevice, listOnlineNames, renameDevice, markSessionDone, } from './devices.js';
 import { promptApproval } from './prompt.js';
 import { touchRecentDir } from './recent-dirs.js';
 import { listDirs } from './browse.js';
@@ -20,6 +20,8 @@ import { readTextFile, writeTextFile, chunkContent } from './files.js';
 import { AUDIO_CHUNK_TTL_MS, MAX_AUDIO_BASE64, STT_SETUP_HINT, findSttServer, transcribe, } from './stt.js';
 import { loadOpenSessions, saveOpenSessions } from './open-sessions.js';
 import { IMAGE_CHUNK_TTL_MS, pruneImages, saveImage } from './images.js';
+import { watchDoneNotes } from './notify.js';
+import { hookAsked, hookState, installHook, rememberHookAsked } from './claude-hook.js';
 const HEARTBEAT_MS = 20_000;
 // 올린 사진 정리 주기 — 보관 기한이 하루라, 오래 켜둔 컴퓨터에서도 반나절 안에 치워진다
 const IMAGE_SWEEP_MS = 6 * 60 * 60 * 1000;
@@ -40,6 +42,18 @@ const PENALTY_INTERVAL_MS = 250;
 const MAX_SESSIONS = 20;
 // 저장 중인 파일 조각을 모아두는 시간 — 중간에 폰이 끊기면 조용히 버린다
 const WRITE_BUFFER_TTL_MS = 60_000;
+// ── "작업이 끝났다" 를 화면 출력만 보고 짐작하는 규칙 ─────────────────────────────
+// Claude Code 훅(notify.ts)이 걸려 있으면 정확한 신호가 오지만, 훅을 못 넣는 환경도 있어서
+// 화면만 보고도 짐작한다. Claude Code 는 일하는 동안 회전 표시·중간 결과를 쉼 없이 그리다가,
+// 대답을 마치면 뚝 멈춘다. 그래서 "한동안 끊이지 않고 출력이 오다가 갑자기 조용해지면 끝난 것"
+// 으로 본다. `ls` 처럼 한 번에 확 뱉고 끝나는 명령은 '이어진 시간' 이 짧아서 걸러진다.
+// 어디까지나 짐작이라 가끔 틀릴 수 있고, 그래서 훅을 걸어두는 쪽을 권한다.
+const BUSY_GAP_MS = 1_000; // 이 안에 다음 출력이 오면 "계속 일하는 중" 으로 이어 본다
+const BUSY_MIN_MS = 3_000; // 이만큼은 이어져야 "일하고 있었다" 로 친다
+const IDLE_MS = 4_000; // 이만큼 조용하면 "끝났다" 로 본다
+// 시간만 보면 "천천히 오래 타이핑한 것" 도 일하는 중으로 잘못 본다(글자마다 화면에 되비치므로).
+// 실제 작업은 출력량이 비교가 안 되게 많아서(회전 표시·중간 결과·빌드 로그) 양으로 걸러낸다.
+const BUSY_MIN_BYTES = 2048;
 // 폰의 폴더 탐색기를 열 때 "지금 셸이 있는 폴더"에서 시작하려면, 세션을 시작한 폴더가 아니라
 // 셸 프로세스의 실제 작업 폴더를 봐야 한다(사용자가 cd 로 옮겨 다니므로). 리눅스는 /proc 로 바로 알 수 있고,
 // 없는 OS(맥·윈도)에서는 세션 시작 폴더로 되돌아간다.
@@ -51,6 +65,14 @@ function liveCwd(session) {
         return session.cwd;
     }
 }
+// 접속을 허용하면서 "이 컴퓨터가 지금 뭘 해줄 수 있는지" 를 함께 알려준다.
+// 지금은 받아쓰기 하나뿐이다: 음성인식 서버가 있으면 폰이 녹음을 이리로 보내고(품질이 좋고
+// 목소리가 컴퓨터 밖으로 안 나감), 없으면 폰이 브라우저 받아쓰기로 알아서 넘어간다.
+// 목록(devices) 대신 여기에 실어 보내는 이유: 목록 테이블은 정해진 칸만 받는데 이건 그 칸이 없고,
+// 어차피 접속하는 그 순간의 상태가 정확하다(서버를 도중에 켜고 끌 수 있으므로).
+function capsPayload(session, sttReady) {
+    return encryptFrame(JSON.stringify({ stt: sttReady }), session.frameKey);
+}
 function resolveShell() {
     if (process.platform === 'win32')
         return process.env.COMSPEC ?? 'powershell.exe';
@@ -69,6 +91,41 @@ function readControl(data, key) {
         return null;
     }
 }
+// Claude Code 완료 알림 훅을 아직 안 걸어둔 사람에게 딱 한 번 물어본다.
+// 남의 설정 파일을 손대는 일이라 말없이 하지 않는다. 화면 앞에 사람이 없는 곳(도커·서비스)에서는
+// 물어볼 수가 없으니 조용히 넘어가고, `shellbase hook install` 로 언제든 직접 걸 수 있다.
+async function offerClaudeHook(options) {
+    if (options.hook === false)
+        return;
+    const state = hookState();
+    if (state === 'installed')
+        return;
+    if (state === 'no-claude')
+        return;
+    if (state === 'unreadable') {
+        console.log('⚠️  Claude Code 설정 파일(~/.claude/settings.json)을 읽을 수 없어서 완료 알림 훅은 건너뛰어요.\n' +
+            '   화면 출력을 보고 짐작하는 방식으로는 계속 알려드려요.');
+        return;
+    }
+    if (hookAsked())
+        return;
+    if (!process.stdin.isTTY) {
+        console.log('ℹ️  Claude Code 작업 완료를 더 정확히 알려면 `shellbase hook install` 을 한 번 실행해주세요.\n' +
+            '   지금은 화면 출력을 보고 짐작하는 방식으로 알려드려요.');
+        return;
+    }
+    rememberHookAsked();
+    const yes = await promptApproval('\n🔔 Claude Code 가 작업을 마치면 폰에 알려드릴까요?\n' +
+        '   (~/.claude/settings.json 에 알림 한 줄을 넣어요. 원래 설정은 그대로 두고 백업도 남겨요) (y/N): ', 30_000);
+    if (!yes) {
+        console.log('   넘어갈게요. 나중에 원하시면 `shellbase hook install` 로 걸 수 있어요.');
+        return;
+    }
+    const result = installHook();
+    console.log(result.ok ? `   ✅ ${result.message}` : `   ⚠️  ${result.message}`);
+    if (result.ok)
+        console.log('   이미 켜져 있는 Claude Code 는 다시 시작해야 적용돼요.');
+}
 export async function runAgent(options) {
     const { cb, memberId } = await requireClient();
     // 여기서 한 번 호출해서 토큰이 살아있는지 먼저 확인 (만료됐으면 세션을 띄우기 전에 알려주는 게 낫다)
@@ -141,6 +198,51 @@ export async function runAgent(options) {
         const wait = Math.max(0, interval - (Date.now() - session.lastSentAt));
         session.pendingFlush = setTimeout(() => void flush(session), wait);
     };
+    // ── 작업 완료 알림 ──────────────────────────────────────────────────────────
+    // 폰에 두 가지 방법으로 알린다:
+    //   ① 실시간 신호 — 앱을 켜두고 있으면 곧바로 뜬다
+    //   ② 목록 row 의 done_at — 나중에 앱을 열어봐도 "그 사이에 끝났다" 는 표시가 남아 있다
+    // ②가 없으면 폰이 꺼져 있던 동안 끝난 작업을 영영 모르게 되므로 둘 다 남긴다.
+    const announceDone = (session, why) => {
+        if (session.closing)
+            return;
+        const at = new Date().toISOString();
+        console.log(`✅ "${session.name}" — ${why}`);
+        void send({ kind: 'session_done', to: session.deviceId });
+        if (session.rowId) {
+            markSessionDone(cb, session.rowId, at).catch(() => {
+                // 목록에 못 남겨도 실시간 신호는 이미 갔다 — 세션 동작에는 영향 없음
+            });
+        }
+    };
+    // 출력이 이어지는지 끊겼는지를 따라가며, 조용해지는 순간을 잡는다 (규칙은 위 상수 설명 참고)
+    const trackBusy = (session, bytes) => {
+        const now = Date.now();
+        // 직전 출력과의 간격이 짧으면 "계속 이어지는 중", 오래 쉬었다 왔으면 거기서 새로 시작
+        if (now - session.lastOutputAt > BUSY_GAP_MS) {
+            session.busySince = now;
+            session.busyBytes = 0;
+        }
+        session.busyBytes += bytes;
+        session.lastOutputAt = now;
+        if (session.idleTimer)
+            clearTimeout(session.idleTimer);
+        session.idleTimer = setTimeout(() => {
+            session.idleTimer = null;
+            if (session.closing || session.hookSeen)
+                return;
+            // 짧게 뱉고 끝난 명령(ls 등)과, 오래 걸렸지만 출력이 거의 없던 것(타이핑 등)은 넘긴다
+            if (session.lastOutputAt - session.busySince < BUSY_MIN_MS)
+                return;
+            if (session.busyBytes < BUSY_MIN_BYTES)
+                return;
+            // 같은 정적에 두 번 알리지 않는다
+            if (session.lastOutputAt <= session.announcedFor)
+                return;
+            session.announcedFor = session.lastOutputAt;
+            announceDone(session, '작업이 끝난 것 같아요 (화면이 조용해졌어요)');
+        }, IDLE_MS);
+    };
     // stdin 은 프로세스에 하나뿐이라, 세션이 여러 개일 때 승인 프롬프트가 겹치지 않게 한 번에 하나씩 묻는다
     let approvalChain = Promise.resolve();
     function askApproval(session) {
@@ -155,6 +257,7 @@ export async function runAgent(options) {
             await send({
                 kind: approved ? 'connect_approved' : 'connect_denied',
                 to: session.deviceId,
+                ...(approved ? { data: capsPayload(session, sttUrl !== null) } : {}),
             });
         })
             .catch((err) => {
@@ -176,8 +279,10 @@ export async function runAgent(options) {
         }
         if (!stat.isDirectory())
             throw new Error(`폴더가 아니라 파일이에요: ${cwd}`);
+        // 터미널을 띄우기 전에 미리 정해둔다 — 이 값을 세션 환경변수로도 심어야 하기 때문 (아래 env 참고)
+        const deviceId = `desktop-${crypto.randomUUID()}`;
         const session = {
-            deviceId: `desktop-${crypto.randomUUID()}`,
+            deviceId,
             frameKey: generateFrameKey(),
             name: explicitName ?? defaultName(cwd),
             cwd,
@@ -187,7 +292,10 @@ export async function runAgent(options) {
                 cols: 80,
                 rows: 24,
                 cwd,
-                env: process.env,
+                // 이 터미널이 어느 세션인지 환경변수로 심어둔다. 이 안에서 실행되는 모든 것(Claude Code,
+                // 그리고 Claude Code 가 끝날 때 실행하는 `shellbase notify`)이 그대로 물려받으므로,
+                // 알림이 왔을 때 어느 세션인지 바로 알 수 있다 (notify.ts).
+                env: { ...process.env, [SESSION_ENV]: deviceId },
             }),
             screen: new HeadlessTerminal({
                 cols: 80,
@@ -203,6 +311,12 @@ export async function runAgent(options) {
             sendPenaltyUntil: 0,
             pendingFlush: null,
             closing: false,
+            busySince: 0,
+            busyBytes: 0,
+            lastOutputAt: 0,
+            idleTimer: null,
+            announcedFor: 0,
+            hookSeen: false,
         };
         session.screen.loadAddon(session.serializer);
         session.pty.onData((data) => {
@@ -210,6 +324,7 @@ export async function runAgent(options) {
             // 화면 상태를 그대로 따라 그려둔다 (재접속 복원용)
             session.screen.write(data);
             scheduleFlush(session);
+            trackBusy(session, data.length);
         });
         session.pty.onExit(() => {
             console.log(`"${session.name}" 세션의 셸이 종료돼서 세션도 닫아요.`);
@@ -243,6 +358,8 @@ export async function runAgent(options) {
         session.closing = true;
         if (session.pendingFlush !== null)
             clearTimeout(session.pendingFlush);
+        if (session.idleTimer !== null)
+            clearTimeout(session.idleTimer);
         await flush(session);
         sessions.delete(session.deviceId);
         if (session.rowId) {
@@ -277,10 +394,13 @@ export async function runAgent(options) {
         shuttingDown = true;
         clearInterval(heartbeat);
         clearInterval(imageSweep);
+        stopNotes();
         for (const session of [...sessions.values()]) {
             session.closing = true;
             if (session.pendingFlush !== null)
                 clearTimeout(session.pendingFlush);
+            if (session.idleTimer !== null)
+                clearTimeout(session.idleTimer);
             await flush(session);
             if (session.rowId) {
                 try {
@@ -314,6 +434,20 @@ export async function runAgent(options) {
     await cb.realtime.connect({ userId: `agent-${crypto.randomUUID()}` });
     const channel = await cb.realtime.subscribe(TERMINAL_CATEGORY);
     // 이 채널은 앱의 모든 멤버가 공유하므로, 프레임 내용(data)은 세션별 키로 암호화해서 주고받는다.
+    // Claude Code 훅이 남긴 "대답 마쳤어요" 쪽지를 받는다 (notify.ts).
+    // 훅에서 정확한 신호가 온 세션은, 화면만 보고 짐작하던 쪽을 꺼서 알림이 두 번 뜨지 않게 한다.
+    const stopNotes = watchDoneNotes((note) => {
+        const session = sessions.get(note.sessionId);
+        if (!session || session.closing)
+            return;
+        session.hookSeen = true;
+        if (session.idleTimer) {
+            clearTimeout(session.idleTimer);
+            session.idleTimer = null;
+        }
+        session.announcedFor = session.lastOutputAt;
+        announceDone(session, note.body || 'Claude Code 가 대답을 마쳤어요');
+    });
     const stopMessages = channel.onMessage((msg) => {
         const frame = msg.data;
         if (!frame)
@@ -347,7 +481,11 @@ export async function runAgent(options) {
             //  폰이 "승인 대기 중" 화면에 갇히는 일이 생겼음 — 자동 승인은 기다릴 게 없으므로 항상 응답)
             if (!requireApproval) {
                 session.inputApproved = true;
-                void send({ kind: 'connect_approved', to: session.deviceId });
+                void send({
+                    kind: 'connect_approved',
+                    to: session.deviceId,
+                    data: capsPayload(session, sttUrl !== null),
+                });
                 return;
             }
             if (session.approvalInFlight)
@@ -627,8 +765,9 @@ export async function runAgent(options) {
     void findSttServer().then((url) => {
         sttUrl = url;
         console.log(url
-            ? `🎤 음성인식 서버를 찾았어요: ${url} — 폰에서 마이크로 말할 수 있어요.`
-            : '🎤 음성인식 서버가 없어요 — 폰 마이크 기능은 꺼진 상태예요 (SHELLBASE_STT_URL 로 주소를 지정할 수 있어요).');
+            ? `🎤 이 컴퓨터에서 받아써요: ${url} — 목소리가 컴퓨터 밖으로 나가지 않아요.`
+            : '🎤 이 컴퓨터에는 음성인식 서버가 없어서, 폰이 브라우저 받아쓰기로 대신해요.\n' +
+                '   (직접 띄운 서버를 쓰려면 SHELLBASE_STT_URL 로 주소를 지정하세요)');
     });
     // 올린 사진은 하루가 지나면 치운다. 예전엔 "새 사진을 저장할 때"만 청소해서, 사진을 한동안 안 올리면
     // 기한이 지난 파일이 계속 남아 있었다 — 시작할 때 한 번, 그리고 켜져 있는 동안 주기적으로도 돌린다.
@@ -652,6 +791,7 @@ export async function runAgent(options) {
     console.log(requireApproval
         ? '접속할 때마다 이 화면에서 승인(y)을 물어봐요. (--require-approval)'
         : '내 계정으로 로그인한 폰에서는 바로 입력할 수 있어요. 매번 확인받고 싶으면 --require-approval 로 실행하세요.');
+    await offerClaudeHook(options);
     // ── 지난번에 열려 있던 세션 복구 (컴퓨터·컨테이너 재시작 후 자동으로 원래 상태로)
     if (options.restore === false) {
         console.log('이전 세션 복구는 건너뛰어요 (--no-restore)');

package/dist/claude-hook.js

@@ -0,0 +1,145 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { CONFIG_DIR } from './config.js';
+// Claude Code 에 "대답을 마치면 shellbase 에 알려줘" 를 걸어두는 부분.
+//
+// Claude Code 는 설정 파일(~/.claude/settings.json)의 Stop 훅에 적힌 명령을 대답이 끝날 때마다
+// 실행해준다. 여기에 `shellbase notify` 한 줄을 넣어두면 완료 시점을 정확히 알 수 있다.
+// (넣지 않아도 화면 출력을 보고 짐작은 하지만, 훅이 있으면 훨씬 정확하다 — agent.ts 참고)
+//
+// 남의 설정 파일을 손대는 일이라 규칙을 지킨다:
+//   · 원래 있던 내용은 하나도 건드리지 않고 우리 줄만 더한다 (다른 알림 훅과 함께 잘 동작한다)
+//   · 고치기 전에 같은 폴더에 백업을 남긴다
+//   · JSON 이 깨져 있으면 아무것도 하지 않는다 (섣불리 고치면 설정 전체가 날아간다)
+const SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
+const HOOK_COMMAND = 'shellbase notify';
+// 물어봤는데 "아니요" 한 사람에게 매번 다시 묻지 않기 위해 답을 기억해둔다
+const CHOICE_PATH = path.join(CONFIG_DIR, 'claude-hook.json');
+function readSettings() {
+    let raw;
+    try {
+        raw = fs.readFileSync(SETTINGS_PATH, 'utf8');
+    }
+    catch {
+        // 파일이 아직 없는 건 정상 — 빈 설정에서 시작한다
+        return { ok: true, value: {} };
+    }
+    if (raw.trim() === '')
+        return { ok: true, value: {} };
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return { ok: false };
+        return { ok: true, value: parsed };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+function stopGroups(settings) {
+    const hooks = settings.hooks;
+    if (!hooks || typeof hooks !== 'object')
+        return [];
+    const stop = hooks.Stop;
+    return Array.isArray(stop) ? stop : [];
+}
+function hasOurHook(groups) {
+    return groups.some((group) => (group?.hooks ?? []).some((entry) => (entry?.command ?? '').includes(HOOK_COMMAND)));
+}
+export function hookState() {
+    if (!fs.existsSync(path.join(os.homedir(), '.claude')))
+        return 'no-claude';
+    const settings = readSettings();
+    if (!settings.ok)
+        return 'unreadable';
+    return hasOurHook(stopGroups(settings.value)) ? 'installed' : 'absent';
+}
+export function installHook() {
+    const settings = readSettings();
+    if (!settings.ok) {
+        return {
+            ok: false,
+            message: `${SETTINGS_PATH} 의 내용이 올바른 JSON 이 아니라서 건드리지 않았어요. 파일을 고친 뒤 \`shellbase hook install\` 로 다시 시도해주세요.`,
+        };
+    }
+    const value = settings.value;
+    const groups = stopGroups(value);
+    if (hasOurHook(groups))
+        return { ok: true, message: '이미 걸려 있어요.' };
+    // 원래 있던 훅들 뒤에 우리 것만 더한다
+    const nextGroups = [
+        ...groups,
+        { hooks: [{ type: 'command', command: HOOK_COMMAND }] },
+    ];
+    const hooks = value.hooks && typeof value.hooks === 'object' && !Array.isArray(value.hooks)
+        ? { ...value.hooks }
+        : {};
+    hooks.Stop = nextGroups;
+    const next = { ...value, hooks };
+    try {
+        fs.mkdirSync(path.dirname(SETTINGS_PATH), { recursive: true });
+        // 고치기 전 백업 — 뭔가 잘못돼도 되돌릴 수 있게
+        if (fs.existsSync(SETTINGS_PATH)) {
+            fs.copyFileSync(SETTINGS_PATH, `${SETTINGS_PATH}.shellbase-backup`);
+        }
+        fs.writeFileSync(SETTINGS_PATH, `${JSON.stringify(next, null, 2)}\n`);
+    }
+    catch (err) {
+        return { ok: false, message: `설정 파일을 저장하지 못했어요: ${err.message}` };
+    }
+    return {
+        ok: true,
+        message: `${SETTINGS_PATH} 에 완료 알림 훅을 넣었어요. (원본은 settings.json.shellbase-backup 에 백업)`,
+    };
+}
+export function removeHook() {
+    const settings = readSettings();
+    if (!settings.ok) {
+        return { ok: false, message: `${SETTINGS_PATH} 의 JSON 이 깨져 있어서 건드리지 않았어요.` };
+    }
+    const value = settings.value;
+    const groups = stopGroups(value);
+    if (!hasOurHook(groups))
+        return { ok: true, message: '걸려 있지 않아요 — 지울 것이 없어요.' };
+    // 우리 명령만 빼고, 그 결과 빈 껍데기가 된 묶음도 정리한다 (남의 훅은 그대로 둔다)
+    const nextGroups = groups
+        .map((group) => ({
+        ...group,
+        hooks: (group?.hooks ?? []).filter((entry) => !(entry?.command ?? '').includes(HOOK_COMMAND)),
+    }))
+        .filter((group) => group.hooks.length > 0);
+    const hooks = { ...value.hooks };
+    if (nextGroups.length > 0)
+        hooks.Stop = nextGroups;
+    else
+        delete hooks.Stop;
+    const next = { ...value, hooks };
+    try {
+        fs.copyFileSync(SETTINGS_PATH, `${SETTINGS_PATH}.shellbase-backup`);
+        fs.writeFileSync(SETTINGS_PATH, `${JSON.stringify(next, null, 2)}\n`);
+    }
+    catch (err) {
+        return { ok: false, message: `설정 파일을 저장하지 못했어요: ${err.message}` };
+    }
+    return { ok: true, message: `${SETTINGS_PATH} 에서 완료 알림 훅을 뺐어요.` };
+}
+// "물어보지 마세요" 를 기억해두는 부분 — 한 번 거절한 사람에게 매번 묻지 않기 위해서다
+export function hookAsked() {
+    try {
+        return JSON.parse(fs.readFileSync(CHOICE_PATH, 'utf8'))?.asked === true;
+    }
+    catch {
+        return false;
+    }
+}
+export function rememberHookAsked() {
+    try {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+        fs.writeFileSync(CHOICE_PATH, JSON.stringify({ asked: true }, null, 2), { mode: 0o600 });
+    }
+    catch {
+        // 기억 못 해도 큰 문제는 아니다 — 다음에 한 번 더 물어볼 뿐
+    }
+}
+export const CLAUDE_SETTINGS_PATH = SETTINGS_PATH;

package/dist/cli.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
+import { createRequire } from 'node:module';
 import { Command } from 'commander';
 import { login, logout, whoami } from './auth.js';
 import { runAgent } from './agent.js';
+import { writeDoneNote } from './notify.js';
+import { hookState, installHook, removeHook, CLAUDE_SETTINGS_PATH } from './claude-hook.js';
 // 실시간 기능(realtime.subscribe)이 Node 의 네이티브 WebSocket(Node 22+)에 의존해서,
 // Node 20 에서는 조용히 SSE 모드로 떨어져 "네트워크가 막혔다"는 헷갈리는 에러만 남기고 죽는다.
 // 미리 버전을 확인해서 원인을 바로 알려준다.
@@ -11,8 +14,14 @@ if (major < 22) {
         'https://nodejs.org 에서 최신 버전을 설치하거나, nvm 을 쓰신다면 `nvm install 22 && nvm use 22` 후 다시 시도해주세요.');
     process.exit(1);
 }
+// 설치 스크립트가 "제대로 깔렸는지" 확인할 때 `shellbase --version` 을 부른다.
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
 const program = new Command();
-program.name('shellbase').description('내 컴퓨터 터미널을 폰에서 접속할 수 있게 해주는 에이전트');
+program
+    .name('shellbase')
+    .description('내 컴퓨터 터미널을 폰에서 접속할 수 있게 해주는 에이전트')
+    .version(version, '-v, --version', '설치된 버전 보기');
 program
     .command('login')
     .description('구글 계정으로 로그인 (처음이면 자동으로 가입도 돼요)')
@@ -39,9 +48,59 @@ program
     .option('--require-approval', '폰에서 접속할 때마다 이 컴퓨터에서 y 로 승인해야 입력이 가능해요 (기본: 내 계정이면 바로 허용)')
     .option('--auto-approve', '(옛 옵션 — 이제 기본 동작이라 넣지 않아도 같아요)')
     .option('--no-restore', '지난번에 열려 있던 세션들을 자동으로 다시 띄우지 않아요')
+    .option('--no-hook', 'Claude Code 완료 알림 훅을 걸지 물어보지 않아요')
+    .option('--no-stt', '이 컴퓨터의 음성인식 서버를 쓰지 않아요 (폰이 브라우저 받아쓰기로 넘어가요)')
     .action(async (opts) => {
+    // 아래쪽(stt.ts)에서 보는 값 하나로 모아둔다 — 환경변수로도, 옵션으로도 끌 수 있게
+    if (opts.stt === false)
+        process.env.SHELLBASE_NO_STT = '1';
     await runAgent(opts);
 });
+// Claude Code 의 Stop 훅이 실행하는 명령. 우리가 띄운 터미널 안에서 돌기 때문에 세션을 가리키는
+// 환경변수를 물려받고 있어서, 쪽지 한 장만 남기면 에이전트가 알아서 폰에 알려준다 (notify.ts).
+program
+    .command('notify')
+    .description('지금 세션에서 "작업이 끝났다"고 폰에 알려요 (Claude Code 훅이 자동으로 실행해요)')
+    .option('--title <title>', '알림 제목', 'Claude Code')
+    .option('--body <body>', '알림 내용', '작업이 끝났어요')
+    .action((opts) => {
+    // 세션 밖(그냥 터미널)에서 실행되면 알릴 곳이 없다 — 조용히 넘어간다.
+    // 훅은 Claude Code 를 쓸 때마다 실행되므로, 여기서 시끄럽게 굴면 안 된다.
+    writeDoneNote(opts.title, opts.body);
+});
+const hook = program
+    .command('hook')
+    .description('Claude Code 작업 완료 알림 켜기/끄기 (~/.claude/settings.json)');
+hook
+    .command('install')
+    .description('Claude Code 가 대답을 마치면 폰에 알리도록 설정해요')
+    .action(() => {
+    const result = installHook();
+    console.log(result.ok ? `✅ ${result.message}` : `⚠️  ${result.message}`);
+    if (result.ok)
+        console.log('이미 켜져 있는 Claude Code 는 다시 시작해야 적용돼요.');
+});
+hook
+    .command('remove')
+    .description('완료 알림 설정을 다시 빼요 (다른 설정은 그대로 둬요)')
+    .action(() => {
+    const result = removeHook();
+    console.log(result.ok ? `✅ ${result.message}` : `⚠️  ${result.message}`);
+});
+hook
+    .command('status')
+    .description('지금 완료 알림이 걸려 있는지 확인해요')
+    .action(() => {
+    const state = hookState();
+    if (state === 'installed')
+        console.log(`✅ 걸려 있어요 — ${CLAUDE_SETTINGS_PATH}`);
+    else if (state === 'absent')
+        console.log(`⬜ 아직 안 걸려 있어요. \`shellbase hook install\` 로 걸 수 있어요.`);
+    else if (state === 'no-claude')
+        console.log('⬜ 이 컴퓨터에서 Claude Code 를 쓴 흔적이 없어요 (~/.claude 폴더가 없어요).');
+    else
+        console.log(`⚠️  ${CLAUDE_SETTINGS_PATH} 의 내용이 올바른 JSON 이 아니에요.`);
+});
 program.parseAsync(process.argv).catch((err) => {
     console.error('실행 중 문제가 생겼어요:', err instanceof Error ? err.message : err);
     process.exit(1);

package/dist/config.js

@@ -15,3 +15,9 @@ export const CREDENTIALS_PATH = path.join(CONFIG_DIR, 'credentials.json');
 // 프레임 전체가 세션별 키로 암호화돼 있어서, 이 문자열이 제대로 풀린다는 건 보낸 쪽이 그 키
 // (= devices 테이블의 내 row, RLS 로 주인만 읽을 수 있음)를 가지고 있었다는 증거가 된다.
 export const CONTROL_TOKEN = 'shellbase-control-v1';
+// Claude Code 가 "대답을 마쳤다"고 알려오는 쪽지를 놓아두는 곳 (notify.ts).
+// 훅이 실행하는 `shellbase notify` 가 여기에 파일을 하나 떨어뜨리면, 에이전트가 주워서 지운다.
+export const NOTIFY_DIR = path.join(CONFIG_DIR, 'notify');
+// 세션 터미널에 심어두는 환경변수 이름 — Claude Code 훅은 우리가 띄운 셸의 자식 프로세스라
+// 이 값을 그대로 물려받는다. 덕분에 "어느 세션이 끝났는지"를 따로 알아낼 필요가 없다.
+export const SESSION_ENV = 'SHELLBASE_SESSION_ID';

package/dist/devices.js

@@ -51,3 +51,9 @@ export async function listOnlineNames(cb) {
 export async function renameDevice(cb, rowId, deviceName) {
     await cb.database.updateData(DEVICES_TABLE_ID, rowId, { data: { device_name: deviceName } });
 }
+// "이 세션에서 작업이 끝났다" 는 표시를 목록 row 에 남긴다.
+// 실시간 신호와 별개로 이걸 남겨두는 이유: 폰이 꺼져 있거나 앱을 닫아둔 사이에 끝난 작업도
+// 나중에 앱을 열었을 때 "● 끝남" 으로 보여주기 위해서다 (실시간 신호는 그 순간 놓치면 끝).
+export async function markSessionDone(cb, rowId, at) {
+    await cb.database.updateData(DEVICES_TABLE_ID, rowId, { data: { done_at: at } });
+}

package/dist/notify.js

@@ -0,0 +1,114 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { NOTIFY_DIR, SESSION_ENV } from './config.js';
+// 오래 남은 쪽지는 무시한다 — 에이전트를 껐다 켠 뒤 며칠 전 알림이 갑자기 뜨면 오히려 헷갈린다
+const NOTE_STALE_MS = 60_000;
+function isNote(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const note = value;
+    return (typeof note.sessionId === 'string' &&
+        typeof note.title === 'string' &&
+        typeof note.body === 'string' &&
+        typeof note.at === 'string');
+}
+// `shellbase notify` 쪽에서 부른다. 쪽지를 남길 수 없으면(세션 밖에서 실행 등) false 를 돌려준다.
+export function writeDoneNote(title, body) {
+    const sessionId = process.env[SESSION_ENV];
+    if (!sessionId)
+        return false;
+    const note = { sessionId, title, body, at: new Date().toISOString() };
+    try {
+        fs.mkdirSync(NOTIFY_DIR, { recursive: true, mode: 0o700 });
+        // 에이전트가 반쯤 쓰인 파일을 주워 읽지 않도록, 다 쓴 뒤 이름을 바꿔 넣는다
+        const temp = path.join(NOTIFY_DIR, `.${crypto.randomUUID()}.tmp`);
+        const final = path.join(NOTIFY_DIR, `${crypto.randomUUID()}.json`);
+        fs.writeFileSync(temp, JSON.stringify(note), { mode: 0o600 });
+        fs.renameSync(temp, final);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// 에이전트 쪽에서 부른다. 쪽지가 도착할 때마다 onNote 를 불러주고, 멈추는 함수를 돌려준다.
+//
+// 파일 감시(fs.watch)는 편하지만 환경에 따라(도커의 특정 파일시스템, 네트워크 드라이브 등)
+// 아예 동작하지 않는 경우가 있어서, 주기적으로 직접 훑어보는 방법을 함께 둔다 — 감시가 되면
+// 즉시, 안 되더라도 늦어도 몇 초 안에는 전달된다.
+const SWEEP_MS = 3_000;
+export function watchDoneNotes(onNote) {
+    try {
+        fs.mkdirSync(NOTIFY_DIR, { recursive: true, mode: 0o700 });
+    }
+    catch {
+        // 폴더를 못 만들면 훅 알림은 못 받지만 세션 자체는 정상 동작해야 한다 (화면 감지로 대신함)
+        return () => { };
+    }
+    let stopped = false;
+    // 감시와 주기 훑기가 같은 쪽지를 두 번 집는 일이 없도록, 집는 순간 지우고 이름을 기억해둔다
+    const taken = new Set();
+    function sweep() {
+        if (stopped)
+            return;
+        let names;
+        try {
+            names = fs.readdirSync(NOTIFY_DIR);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (!name.endsWith('.json') || taken.has(name))
+                continue;
+            taken.add(name);
+            const file = path.join(NOTIFY_DIR, name);
+            let raw;
+            try {
+                raw = fs.readFileSync(file, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            try {
+                fs.unlinkSync(file);
+            }
+            catch {
+                // 못 지워도 taken 에 있으니 다시 집지는 않는다
+            }
+            taken.delete(name);
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                continue;
+            }
+            if (!isNote(parsed))
+                continue;
+            if (Date.now() - new Date(parsed.at).getTime() > NOTE_STALE_MS)
+                continue;
+            onNote(parsed);
+        }
+    }
+    let watcher = null;
+    try {
+        watcher = fs.watch(NOTIFY_DIR, () => sweep());
+        // 감시 자체가 실패해도(권한 등) 주기 훑기로 계속 동작해야 한다
+        watcher.on('error', () => { });
+    }
+    catch {
+        watcher = null;
+    }
+    const timer = setInterval(sweep, SWEEP_MS);
+    // 이 타이머 때문에 프로세스가 안 꺼지는 일이 없게 한다
+    timer.unref?.();
+    // 에이전트가 꺼져 있는 동안 쌓인 쪽지가 있을 수 있으니 한 번 훑고 시작한다
+    sweep();
+    return () => {
+        stopped = true;
+        clearInterval(timer);
+        watcher?.close();
+    };
+}

package/dist/stt.js

@@ -24,6 +24,10 @@ async function isAlive(baseUrl) {
 }
 // 시작할 때 한 번 찾아두고, 못 찾으면 요청이 올 때 다시 한 번 찾아본다(그 사이에 켰을 수도 있으니)
 export async function findSttServer() {
+    // 이 컴퓨터의 음성인식 서버를 일부러 안 쓰고 싶을 때 (폰이 브라우저 받아쓰기로 넘어간다).
+    // 5005 포트를 다른 프로그램이 쓰고 있는 경우에도 필요하다.
+    if (process.env.SHELLBASE_NO_STT)
+        return null;
     for (const url of candidates()) {
         if (await isAlive(url))
             return url;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shellbase",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "내 컴퓨터 터미널(특히 Claude Code 세션)을 폰 브라우저로 실시간 접속하게 해주는 데스크톱 에이전트",
   "type": "module",
   "bin": {