# Huddle 설치 안내 (Claude Code용)

이 문서는 **사용자의 Claude Code가 읽고 그대로 진행하는 설치 절차**입니다.
사용자가 "ctalk.cupia.ai로 Huddle 설치해줘", "Huddle 연결해줘"처럼 요청하면 아래 순서대로 진행하세요.

Huddle은 회사 동료들의 Claude Code를 팀 채널로 묶어, 팀장이 팀원의 진행상황을 물으면 팀원 PC의 Claude Code가 작업 기록을 요약해 답하는 사내 서비스입니다.
웹 콘솔: https://ctalk.cupia.ai

## 진행 원칙

- 명령은 모두 **사용자의 PC 터미널**에서 실행합니다. 실행하기 전에 무엇을 하는지 한 줄로 알리고, 사용자가 허락한 뒤 실행하세요.
- **가입 코드·이름·초대 코드는 대화로 묻거나 받지 마세요.** 브라우저 화면에서 사용자가 직접 입력합니다.
- **자동 응답 동의를 사용자 대신 켜지 마세요.** 본인이 직접 정합니다.
- `~/.huddle/config.json`의 토큰을 출력하거나 다른 곳에 보내지 마세요.
- 문제가 생기면 오류 문구를 그대로 사용자에게 보여 주고 아래 "문제 해결"을 참고하세요.

## 1. 이미 설치되어 있는지 확인

```
huddle --version
claude mcp list
```

- 둘 다 정상이고 `claude mcp list`에 `huddle ... Connected`가 보이면 `huddle update`로 최신 버전인지 확인한 뒤 **4단계(로그인 확인)**로 갑니다. (`huddle update`가 없다는 오류가 나오면 오래된 버전이니 2단계로 다시 설치합니다.)
- `huddle`이 없으면 2단계로 갑니다.

## 2. 설치

운영체제에 맞는 한 줄을 실행합니다. 설치 스크립트는 내려받은 파일의 체크섬을 확인합니다.

- **macOS · Linux**
  ```
  curl -fsSL https://ctalk.cupia.ai/download/install.sh | sh
  ```
  설치 위치: `~/.local/bin/huddle`. 이 폴더가 PATH에 없으면 이번 세션에서는 `~/.local/bin/huddle`처럼 전체 경로로 실행하고, 사용자에게 PATH 추가 방법(스크립트가 출력한 줄)을 알려 주세요.

- **Windows (PowerShell)**
  ```
  irm https://ctalk.cupia.ai/download/install.ps1 | iex
  ```
  Claude Code의 셸이 bash(Git Bash)라면: `powershell -NoProfile -Command "irm https://ctalk.cupia.ai/download/install.ps1 | iex"`.
  설치 위치: `%LOCALAPPDATA%\Huddle\huddle.exe` (PATH는 새 터미널부터 적용되므로 이번 세션에서는 전체 경로 사용).

## 3. Claude Code에 연결

```
huddle install
```

Claude Code에 MCP 서버 `huddle`과 작업 기록용 훅을 등록합니다(사용자의 `~/.claude` 설정이 바뀐다고 알려 주세요). 작업 기록은 이 PC의 `~/.huddle`에만 저장됩니다.

## 4. 로그인 · 가입

```
huddle me
```

- 계정 정보가 나오면(승인됨) 5단계로 갑니다.
- "로그인 정보가 없습니다" 류의 오류면 아래를 실행합니다. **최대 10분 동안 브라우저 승인을 기다리므로 타임아웃을 넉넉히(10분) 주세요.**

```
huddle login
```

브라우저가 열리고 확인 코드가 표시됩니다. 사용자에게 이렇게 안내하세요.

1. 브라우저의 확인 코드가 터미널에 나온 코드와 같은지 확인
2. 처음이면: 이름 · 소속 · **가입 코드**(팀장이나 관리자에게 받은 코드)를 입력하고 [가입 신청하고 연결]
3. 이미 가입했으면: 기존 PC의 웹 콘솔(내 정보 → 새 PC 연결)에 이 확인 코드를 넣거나, 관리자에게 확인 코드를 알려 연결 요청

브라우저가 열리지 않으면 터미널에 출력된 주소를 사용자에게 보여 주고 직접 열게 하세요.
끝나면 터미널에 "연결했습니다"가 나옵니다. 가입 직후에는 "승인 대기 중"이며, 팀장이나 관리자가 승인해야 쓸 수 있습니다.

## 5. Claude Code 다시 시작

MCP 서버는 Claude Code가 시작할 때 불러옵니다. 사용자에게 **Claude Code를 종료했다가 다시 시작**하라고 안내하세요.

## 6. 팀 채널 참가 (다시 시작한 뒤)

공유할 프로젝트 폴더에서 Claude Code를 열고 이렇게 말하면 됩니다.

> huddle 팀1 채널 들어가줘

브라우저에서 팀장에게 받은 초대 코드와 자동 응답 동의 여부를 입력하면, 그 폴더가 채널에 연결됩니다. 연결한 폴더의 작업만 공유됩니다.

## 설치가 끝나면 사용자에게 알려 줄 것

- 상태 확인: "huddle 내 상태 보여줘"
- 팀장이 물으면: 이 PC의 Claude Code가 할 일 목록·오늘 커밋 제목·테스트 결과·바뀐 파일 경로를 요약해 답합니다(자동 응답을 켠 경우). 요약은 그 채널 팀장과 회사 관리자가 볼 수 있습니다. 지시 원문과 Claude 응답 원문, 파일 내용은 보내지 않습니다.
- 웹 콘솔: https://ctalk.cupia.ai ("huddle 웹 열어줘"로 로그인)
- 업데이트: Huddle은 Claude Code가 켜질 때 새 버전을 자동으로 설치합니다. Claude Code를 다시 시작하면 적용됩니다. 바로 받으려면 "huddle 업데이트해줘".
- 사용자 설명서: https://ctalk.cupia.ai/download/huddle-user-guide.pptx

## 무엇을 기록하고 무엇을 보내나요

- **기록 범위**: Claude Code 훅은 모든 세션에서 불리지만, **채널 참가가 끝난(연결한) 폴더에서만** `~/.huddle/journal`에 기록합니다. 연결하지 않은 폴더나 승인 대기 중인 폴더는 아무것도 쓰지 않습니다. 훅을 통째로 끄려면 환경 변수 `HUDDLE_DISABLE=1`. 채널에서 나가면(`huddle leave`) 그 폴더 기록도 지웁니다.
- **로컬에 기록하는 것**: 할 일 목록(TodoWrite·Task 제목과 상태), 수정한 파일의 저장소 안 경로, 실행한 명령의 종류(test/build/git/기타, 성공·실패 — 명령 원문은 아님), 세션 상태(작업 중/쉬는 중/끝남).
- **요청이 오면 더 읽는 것**: 이 폴더 git의 오늘(18시간) 내 커밋 제목(본인 이메일), 바뀐 파일 경로, 브랜치. 비밀값처럼 보이는 줄·`.env` 같은 파일은 뺍니다.
- **기본으로 기록하지 않는 것**: 지시 원문 앞부분(prompt_head), Claude 마지막 메시지(last_msg). 본인이 `huddle config share.prompt_head on`, `huddle config share.last_message on`으로 켠 경우에만 기록·사용합니다. 파일 내용과 명령 원문은 어떤 경우에도 보내지 않습니다.
- **요약 방식**: 기본은 이 PC의 `claude -p`로 위 데이터만 넣어 요약하고(도구·MCP·사용자 설정 없이 실행), 실패하면 규칙 요약으로 보냅니다. 사용량은 그 CLI가 쓰는 로그인 계정이나 API 키에 잡힙니다. 모델은 CLI 기본값 또는 `huddle config model <이름>`. 사용자 설정을 읽지 않으므로 `~/.claude/settings.json`에만 넣은 게이트웨이·모델 설정은 쓰이지 않습니다. LLM을 쓰지 않으려면 `huddle config summarizer rules` (재시작 없이 바로 적용).
- **수집 항목 전체**: 브랜치, 최근 18시간 본인 커밋 해시·제목(git 이메일이 없으면 수집 안 함), 바뀐·수정한 파일의 저장소 안 경로와 변경 줄 수, 할 일 제목·상태, 테스트·빌드 성공·실패와 시각, 세션 상태와 마지막 활동 시각. 할 일·커밋 제목에 민감한 문구를 쓰면 그대로 요약 재료가 되니 주의하세요.
- **누가 보나**: 그 채널 팀장과 회사 관리자(관리자 열람은 기록되어 팀장에게 보임).
- **확인**: `huddle preview`(이 폴더에서 지금 보낼 데이터), `huddle sent`(보낸 기록), `huddle config`(설정).

## 응답 방식 (채널·폴더마다)

- **응답 안 함**(기본): 팀장 요청에 답하지 않습니다.
- **자동 응답**: 확인 없이 요약을 보냅니다. 오프라인이면 마지막 스냅샷(7일 이내)으로 답합니다.
- **보고 승인**: 바로 보내지 않고 기다립니다. Claude Code에 "huddle 승인 대기 보여줘"라고 하면 요청과 초안이 나오고, "보내줘"라고 하면 확인 폼에서 내용을 고친 뒤 [보내기]를 체크해야 전송됩니다(24시간 안, 늦으면 "늦은 응답"으로 표시). 터미널: `huddle inbox`, `huddle reply <id> [--edit|--decline]`. 오프라인 자동 응답은 하지 않습니다.
- 바꾸기: 웹 콘솔 내 정보, Claude Code("huddle 응답 방식을 보고 승인으로 바꿔줘"), 터미널 `huddle consent on|off|review`.

## 전역·채널 프롬프트 (공통 설계 지침을 같은 품질로)

- 관리자(또는 관리자가 지정한 사람)는 **전역 프롬프트**(사내 코딩·보안 규칙, 설계 문서 양식 등)를, 팀장은 **채널 프롬프트**(팀 설계 지시, 컨벤션, 코드·문서 위치)를 저장합니다. 작업마다 바뀌는 부분은 `{{대상_모듈}}`처럼 변수로 둡니다.
- 팀원은 Claude Code에서 필요할 때만 씁니다: "허들 프롬프트 보여줘" → "pay-design 프롬프트로 시작해줘". 확인 폼에 **전문과 변수 입력칸**이 뜨고, [이 지시로 이번 작업 시작]을 체크해야 Claude Code에 들어갑니다. 자동으로 들어가는 일은 없습니다.
- 고치면 새 버전이 되고, 다음에 쓸 때 다시 전문을 확인합니다. 누가 어느 버전을 썼는지 팀장·관리자가 볼 수 있습니다(90일 보관).
- **슬래시 명령**: 한 번 확인·승인한 버전은 Claude Code에서 `/mcp__huddle__c_pay-design billing R1`처럼 바로 쓸 수 있습니다(인자는 변수 순서, 공백 구분, 한 줄). 처음 쓰는 버전·고친 버전·포함한 전역이 바뀐 경우는 실행하지 않고 확인 폼으로 안내합니다. 목록은 팀장이 고치면 자동으로 갱신됩니다.
- **게시판 목표에 연결**: 팀장은 목표에 프롬프트를 연결할 수 있습니다(웹 게시판 목표 편집의 "프롬프트", 또는 Claude Code에 "이 목표에 c_pay-design 연결해줘"). 담당자는 `huddle_board`나 웹 게시판에서 시작 방법을 봅니다.
- **전역 포함**: 팀장은 채널 프롬프트에 회사 공통 규칙을 넣을 수 있습니다: `huddle prompt save pay-design --include coding-rules` (최대 5개). 쓸 때 "공통 지침 → 전역 규칙 → 팀 지시" 순서로 합쳐지고, 보안·금지 사항은 전역이, 위치·양식은 팀 지시가 우선합니다.
- 터미널: `huddle prompt list`, `huddle prompt show <이름>`, `huddle prompt use <이름> [--var 이름=값] [--out 파일]`, 관리 `huddle prompt save <이름> --title … --file 본문.md [--global|--channel 채널] [--target alias]`, `huddle prompt delete <이름>`.

## 연결 범위

- **하위 폴더**: git 저장소 루트 단위로 연결합니다. 저장소 안 어느 하위 폴더에서 Claude Code를 열어도 같은 연결입니다. git이 아닌 폴더는 그 폴더 자체가 단위입니다.
- **git worktree**: worktree마다 루트가 달라 따로 연결해야 합니다.
- **한 PC의 여러 폴더**: 같은 채널에 다른 폴더를 연결하면 별도 이름(예: 홍길동-2)이 생기고, 폴더마다 따로 답합니다.
- **같은 계정의 PC 여러 대**: 다른 PC에서 같은 채널에 참가하면 같은 이름(슬롯)으로 연결되어, **마지막으로 접속한 PC 하나만** 답하고 먼저 켠 PC의 연결은 끊깁니다. 두 PC가 따로 답하게 하려면 두 번째 PC의 프로젝트 폴더에서 `huddle join <채널> --new-slot`으로 새 이름을 만드세요(자동 응답은 꺼진 채로 만들어짐).
- **같은 이름을 다시 참가**하면 그 이름의 자동 응답 동의가 이번에 고른 값으로 바뀝니다.

## 업데이트·제거

- 업데이트: Claude Code가 켜질 때 자동으로 새 버전을 설치합니다(다음 시작부터 적용). 바로 받으려면 `huddle update`. 자동 업데이트를 끄려면 `HUDDLE_NO_AUTO_UPDATE=1`.
- 제거: `huddle uninstall` (MCP 등록·훅 제거). 로그인 정보와 기록까지 지우려면 `huddle uninstall --purge`.
- 기계가 읽는 출력: `huddle me|preview|sent|board|members --json` → `{"format": "huddle.v1", "kind": ..., "data": ...}`.

## 문제 해결

| 증상 | 해결 |
|---|---|
| `huddle: command not found` | 전체 경로로 실행 (`~/.local/bin/huddle`, Windows `%LOCALAPPDATA%\Huddle\huddle.exe`) |
| `claude mcp list`에 huddle이 없음 | `huddle install` 다시 실행 후 Claude Code 재시작 |
| "가입 코드가 없거나 만료되었습니다" | 팀장이나 관리자에게 새 가입 코드 요청 |
| "승인 대기 중" | 초대 코드를 준 팀장이나 관리자에게 승인 요청 |
| "확인 코드가 없거나 만료되었습니다" | 10분이 지남. `huddle login`부터 다시 |
| 새 기능(도구)이 안 보임 | `huddle update` 실행 후 Claude Code 재시작 (또는 `/mcp`에서 huddle 재연결) |
| macOS에서 실행이 막힘 | 설치 스크립트로 다시 설치 (서명을 자동으로 붙임) |
