사용법

화면 구성

┌──────────────────────────────────────────────────────────────────────────┐
│ 헤더: [☰] [채팅] [터미널] [파일] [Git] [Team]  📁 프로젝트명  [⚡Harness] [⚙️][🌐][🌙] │
├──────────────┬──┬─────────────────────────────────────────────────────────┤
│  사이드바    │⋮ │                    메인 패널                              │
│  (리사이즈)  │  │  [채팅 | 터미널 | 파일 | Git | Team]                     │
│  서버 선택   │  │                                                           │
│  ──────      │  │  채팅 탭:    Bot 아이콘 + "채팅" 헤더 + 대화 영역          │
│  프로젝트    │  │  터미널 탭:  SquareTerminal 아이콘 + "터미널" 헤더          │
│  목록        │  │  파일 탭:    FolderOpen 아이콘 + "파일" 헤더 + Monaco 에디터│
│  ──────      │  │  Git 탭:     GitBranch 아이콘 + "Git" 헤더 + 브랜치명      │
│  세션 목록   │  │  Team 탭:    Users 아이콘 + "Team" 헤더 + 칸반보드         │
│  + 새 대화   │  │                                                           │
└──────────────┴──┴─────────────────────────────────────────────────────────┘
                ↑ 드래그 핸들

---

사이드바 너비 조절

사이드바와 메인 패널 사이의 **드래그 핸들(⋮)**을 좌우로 끌어 너비를 자유롭게 조절할 수 있습니다.

조작	동작
핸들 드래그	사이드바 너비 조절 (160 px ~ 480 px)
헤더 ☰ 버튼	사이드바 접기 / 펼치기 토글

헤더 로고 영역은 사이드바 너비에 자동으로 맞춰집니다.

---

서버 연결 상태 확인

사이드바 상단에 서버 아이콘과 함께 연결 상태가 표시됩니다.

표시	의미
🟢 초록 점 · 연결됨	WebSocket 연결 정상
⚫ 회색 점 · 연결 중...	연결 시도 중 또는 끊김

연결이 끊기면 3초 후 자동으로 재연결을 시도합니다.

---

프로젝트 선택과 세션

프로젝트 목록

사이드바의 프로젝트 목록에서 작업할 프로젝트를 선택합니다.

• 목록은 서버의 ~/.claude/projects/ 디렉터리에서 자동으로 읽어옵니다.
• 서버를 전환하면 해당 서버의 프로젝트 목록으로 자동 갱신됩니다.
• 프로젝트를 클릭하면 해당 프로젝트의 세션 목록이 표시됩니다.

세션 선택 및 URL 라우팅

세션을 클릭하면 URL이 세션 ID 기반으로 변경됩니다.

/session/{sessionId}

• 세션 ID는 ~/.claude/projects/{프로젝트}/ 디렉터리의 .jsonl 파일명입니다.
• 브라우저 주소를 직접 공유하거나 새로고침해도 동일 세션으로 복원됩니다.

세션 미선택 상태

세션이 선택되지 않은 경우(루트 URL /) 모든 탭에 통합 안내 페이지가 표시됩니다.

📬  세션을 선택하세요
왼쪽 사이드바의 프로젝트 폴더에서 세션을 클릭하거나, 새 채팅을 시작하세요.

새 대화 시작

프로젝트 항목 옆의 + 새 대화 버튼을 클릭하면 새 세션이 자동으로 생성됩니다.

1. 서버에서 UUID 기반 세션 파일 생성 (~/.claude/projects/{id}/{uuid}.jsonl)
2. URL이 /session/{uuid}로 이동
3. 채팅 패널이 열리고 첫 메시지를 입력하면 대화가 시작됩니다

---

헤더 구성

헤더는 세 영역으로 구성됩니다.

[☰] [채팅] [터미널] [파일] [Git] [Team]    📁 프로젝트명    [⚡ Harness]    [⚙️][🌐][🌙]
 ↑  ←────── 탭 버튼 ─────────────────→   ←─ 컨텍스트 ─→  ←─ 상태 ─→   ←─ 설정 ─→

영역	설명
☰	사이드바 접기/펼치기
탭 버튼	패널 전환 (채팅 / 터미널 / 파일 / Git / Team)
📁 프로젝트명	현재 선택된 프로젝트 표시 (hover 시 전체 경로 tooltip)
⚡ Harness	Harness 실행 중일 때만 표시 (활성 에이전트 수 포함)
⚙️	설정 모달
🌐	언어 선택
🌙 / ☀️	다크 / 라이트 모드 전환

탭 패널 헤더

각 탭 패널 상단에는 탭 아이콘 + 탭 제목이 일관된 형식으로 표시됩니다.

탭	아이콘	헤더 추가 정보
채팅	🤖 파란색 Bot	세션 ID (앞 8자) / 토큰 사용량
터미널	🟢 에메랄드 SquareTerminal	연결 상태 뱃지
파일	🟡 앰버 FolderOpen	프로젝트명 (작은 글씨)
Git	🟣 보라 GitBranch	현재 브랜치명
Team	🔵 인디고 Users	팀 선택 드롭다운

---

채팅 (Claude와 대화)

메시지 전송

1. 하단 입력창에 메시지를 입력합니다.
2. Enter 또는 전송 버튼을 클릭합니다.
3. Claude가 스트리밍 방식으로 응답합니다.

권한 모드 선택

입력창 옆의 모드 셀렉터로 Claude의 작업 권한 범위를 설정합니다.

모드	설명
bypassPermissions	모든 도구 사용을 자동 승인 (root 환경에서는 acceptEdits로 자동 전환)
acceptEdits	파일 편집 자동 승인, 기타 도구는 승인 요청
default	모든 도구 사용 전 브라우저에서 승인 요청

root 환경 주의: root 또는 sudo 권한으로 실행된 서버에서는 bypassPermissions를 선택해도 자동으로 acceptEdits로 전환됩니다.

도구 사용 승인

default 모드에서 Claude가 도구(파일 읽기, 코드 실행 등)를 사용하려 할 때 브라우저에 승인 요청 팝업이 표시됩니다.

• 허용: 도구 실행을 승인합니다.
• 거부: 해당 도구 사용을 막습니다.
• 30초 내 응답이 없으면 자동으로 허용 처리됩니다.

코드 블록 복사

채팅 응답의 코드 블록 위에 마우스를 올리면 우상단에 복사 버튼이 나타납니다.

• 클릭하면 코드 전체가 클립보드에 복사됩니다.
• 2초간 체크마크(✓ 복사됨)로 피드백이 표시됩니다.

대화 내보내기 (Markdown)

채팅 헤더 우측의 다운로드 버튼을 클릭하면 현재 대화 내용을 .md 파일로 내려받을 수 있습니다.

대화 중단

응답 생성 중 중지 버튼을 클릭하면 현재 응답을 즉시 중단합니다.

세션 이어서 하기

사이드바에서 이전 세션을 선택하면 해당 대화를 이어서 진행할 수 있습니다.

---

파일 편집기

우측 패널의 파일 탭에서 프로젝트 파일을 탐색하고 편집합니다.

• 왼쪽 파일 트리에서 파일을 클릭하면 Monaco 에디터로 열립니다.
• 에디터 상단에 현재 열린 파일의 전체 경로가 표시됩니다.
• 편집 후 Ctrl+S / Cmd+S 로 저장합니다.

---

터미널

우측 패널의 터미널 탭에서 서버 쉘에 직접 접속합니다.

• 서버에서 node-pty가 정상 빌드된 경우에만 활성화됩니다.
• 터미널을 열면 쉘 프롬프트(bash/zsh)가 바로 표시됩니다.
• 창 크기를 조절하면 터미널도 자동으로 리사이즈됩니다.

# 터미널에서 Claude CLI 직접 실행 예시
claude

# 특정 모드로 실행
claude --print "현재 디렉터리의 파일 목록을 알려줘"

---

Team 탭

Team 탭에서 멀티 에이전트 팀을 생성하고 실행합니다.

팀 목록 및 선택

프로젝트를 선택한 뒤, 상단 드롭다운에서 팀을 선택합니다.

• 팀이 없으면 + 팀 생성 버튼으로 새 팀을 만듭니다.
• YAML 템플릿을 선택하거나 직접 에이전트 구성을 정의할 수 있습니다.

팀 실행

팀을 선택한 뒤 ▶ 실행 버튼을 클릭하면 멀티 에이전트 오케스트레이션이 시작됩니다.

• 각 에이전트의 상태가 칸반 보드 형태로 표시됩니다.
• 실행 중 메시지 로그를 실시간으로 확인할 수 있습니다.

가이드 상태

상태	표시
프로젝트 미선택	FolderOpen 아이콘 + 안내 텍스트
팀 미선택	Users 아이콘 + 팀 선택 안내

---

Harness 진행 상태 뱃지

프로젝트를 선택하고 Harness Engineering 워크플로우가 실행 중이면 헤더에 녹색 뱃지가 표시됩니다.

⚡ Harness  [3]

• 숫자는 현재 활성 에이전트 수를 나타냅니다.
• 5초마다 서버에 상태를 자동으로 폴링합니다.

---

Git 패널

우측 패널의 Git 탭에서 현재 프로젝트의 Git 상태를 확인하고 커밋할 수 있습니다.

기능	설명
변경사항	수정 파일 목록, 스테이징, 커밋, Push / Pull
로그	커밋 히스토리 및 커밋 diff 뷰어
브랜치	브랜치 목록 및 체크아웃
이슈	GitHub Issues 연동 패널

변경사항 탭 — 상하 리사이즈

변경 파일 목록과 diff 뷰어 사이의 **가로 핸들(—)**을 드래그해 영역 비율을 조절할 수 있습니다.

┌────────────────────────────┐
│  변경 파일 목록 (드래그)    │
├────────────────────────────┤  ← 드래그 핸들
│  Diff 뷰어                 │
└────────────────────────────┘

Diff 뷰어 색상

라인 종류	색상
추가 (+)	초록 (emerald)
삭제 (-)	빨강 (red)
헝크 헤더 (@@)	파랑 (blue)
메타 정보	흐린 텍스트

---

모델 선택

채팅 입력창 옆에서 사용할 Claude 모델을 선택할 수 있습니다.

모델	특징
claude-sonnet-4-6	기본값. 속도와 성능 균형
claude-opus-4-6	최고 성능, 복잡한 작업에 적합
claude-haiku-4-5	빠른 응답, 간단한 작업에 적합