hanes 0.1.0

A web UI for managing Claude Code's harness, persona, and settings.

Hanes

Claude Code의 설정 파일을 웹 UI로 관리하는 로컬 도구입니다. settings.json, CLAUDE.md, 메모리 파일, 훅(Hooks) 등을 브라우저에서 편집할 수 있습니다.

---

설치

# 1. 저장소 클론
git clone https://github.com/koclam98/hanes.git
cd hanes

# 2. 가상환경 생성 및 활성화
python -m venv .venv
source .venv/bin/activate       # macOS / Linux
.venv\Scripts\activate          # Windows

# 3. 설치
pip install -e .

---

실행

hanes

실행하면 자동으로 브라우저가 열립니다. (기본 포트 자동 선택)

포트가 충돌하는 경우 다른 빈 포트를 자동으로 찾아서 실행됩니다.

---

화면 구성

┌──┬────────┬──────────────────────────────────┐
│  │        │                                  │
│아 │ 파일   │         편집 영역                │
│이 │ 목록   │                                  │
│콘 │        │                                  │
│바 │        │                                  │
│   │        │                                  │
└──┴────────┴──────────────────────────────────┘

왼쪽 아이콘 사이드바에서 섹션을 선택합니다.

아이콘	섹션	기능
⚙	Settings	Claude Code의 동작 설정 (settings.json) — 모델, 언어, 권한, 환경변수 등
👤	Persona	Claude의 행동 지침 (CLAUDE.md) — 프로젝트별 또는 전역 시스템 프롬프트 편집
🧠	Memory	대화 간 유지되는 메모리 파일 편집 — Claude가 장기적으로 기억할 내용 관리
⚡	Hooks	라이프사이클 훅 관리 — 도구 실행 전/후, 세션 종료 등 이벤트에 쉘 명령어 자동 실행
📁	Paths	Hanes에서 관리할 파일 경로 등록/삭제

---

각 화면 설명

⚙ Settings

Claude Code가 어떻게 동작할지를 설정합니다. settings.json 파일을 폼 UI로 편집하며, 저장 즉시 Claude Code에 반영됩니다.

• Model / Effort / Language: 응답 품질, 언어 등 기본 동작 설정
• Permissions: Claude Code가 실행할 수 있는 명령어/도구의 허용(allow) · 거부(deny) · 확인(ask) 권한 관리
• Environment Variables: Claude Code 실행 환경에 주입할 환경변수 관리
• Raw JSON 모드: 폼으로 편집하기 어려운 항목은 직접 JSON으로 편집

👤 Persona

Claude의 행동 방식, 말투, 역할을 정의하는 CLAUDE.md 파일을 편집합니다. Claude Code는 대화 시작 시 이 파일을 시스템 프롬프트로 읽어들입니다.

• 전역 CLAUDE.md (~/.claude/CLAUDE.md): 모든 프로젝트에 적용
• 프로젝트별 CLAUDE.md (.claude/CLAUDE.md): 해당 프로젝트에서만 적용
• 프리셋 기능: 자주 쓰는 페르소나를 이름 붙여 저장하고 빠르게 불러오기 (localStorage 저장)

🧠 Memory

Claude Code가 대화 간에 기억할 내용을 담은 메모리 파일(.md)을 편집합니다. Claude는 대화 시작 시 지정된 메모리 파일을 자동으로 읽어 컨텍스트로 활용합니다.

• 여러 메모리 파일을 등록해 주제별로 분리 관리 가능
• 새 파일 생성: UI에서 바로 파일 경로와 ID를 지정해 생성

⚡ Hooks

Claude Code의 라이프사이클 이벤트에 맞춰 쉘 명령어를 자동으로 실행합니다. 반복 작업을 자동화하거나 외부 시스템과 연동할 때 사용합니다.

이벤트	시점
PreToolUse	Claude가 도구(tool)를 실행하기 직전
PostToolUse	Claude가 도구(tool)를 실행한 직후
Stop	Claude 응답이 종료될 때
Notification	알림이 발생할 때

📁 Paths

Hanes에서 편집할 파일 경로를 등록합니다. 등록된 경로는 Settings · Persona · Memory 화면의 파일 목록에 나타납니다.

• 여러 프로젝트의 설정 파일을 한 곳에서 관리 가능
• 경로 삭제는 Hanes 목록에서만 제거되며 실제 파일은 삭제되지 않음

---

각 섹션 사용법

Settings

settings.json 파일을 폼 UI로 편집합니다.

항목	설명
Model	사용할 Claude 모델 선택
Effort Level	응답 노력 수준 (low → max)
Language	응답 언어 (예: korean)
Show Turn Duration	턴 소요 시간 표시 여부
Permissions	allow / deny / ask 권한 태그 관리
Environment Variables	환경변수 키-값 추가/삭제

• <> Raw JSON 버튼: 직접 JSON 편집 모드로 전환
• Save 버튼 (또는 Cmd+S): 파일 저장
• 저장 전 변경사항은 파일명 옆 ● 로 표시

---

Persona

CLAUDE.md 파일을 마크다운 에디터로 편집합니다.

프리셋 기능 (우측 패널):

1. 현재 내용을 프리셋으로 저장 → + 저장 클릭 → 이름 입력 → 저장
2. 저장된 프리셋 목록에서 불러오기 클릭 → 에디터에 내용 적용
3. 불러온 후 Save로 파일에 반영

프리셋은 브라우저 localStorage에 저장됩니다.

---

Memory

Claude Code의 메모리 파일(.md)을 편집합니다.

새 메모리 파일 생성:

1. 좌측 하단 + 새 파일 클릭
2. ID, 레이블, 파일 경로 입력
3. 생성 클릭 → 파일 생성 + 목록에 자동 등록

파일이 없는 경로를 입력하면 자동으로 생성됩니다.

---

Hooks

settings.json의 훅(hooks)을 시각적으로 편집합니다.

1. 이벤트 타입 선택 (PreToolUse, PostToolUse, Stop 등)
2. 명령어 입력
3. + 추가 클릭 (또는 Enter)
4. 등록된 훅 목록에서 ✕ 로 삭제
5. Save로 저장

---

Paths

Hanes에서 관리할 파일 경로를 등록/삭제합니다.

경로 추가:

1. 우측 상단 + 경로 추가 클릭
2. 항목 입력:
   • ID: 고유 식별자 (예: my-project-settings)
   • 레이블: 표시 이름 (예: My Project Settings)
   • 경로: 파일 전체 경로 (예: ~/.claude/settings.json)
   • 타입: global / project / memory
3. 추가 클릭

경로 삭제: 목록에서 삭제 클릭

경로 삭제는 Hanes 등록을 해제할 뿐, 실제 파일은 삭제되지 않습니다.

---

기본 등록 경로

설치 직후 아래 경로가 기본으로 등록되어 있습니다:

ID	경로	타입
global-settings	~/.claude/settings.json	global
global-settings-local	~/.claude/settings.local.json	global
global-claude-md	~/.claude/CLAUDE.md	global

---

프로젝트별 파일 추가 방법

Claude Code는 프로젝트별로 settings.json, CLAUDE.md를 가질 수 있습니다.

1. Paths 섹션에서 경로 추가
2. 예시:
   • ID: myproject-settings
   • 경로: /Users/yourname/projects/myproject/.claude/settings.json
   • 타입: project

---

개발 모드 실행 (소스 수정 시)

# 터미널 1 — 백엔드
source .venv/bin/activate
uvicorn hanes.main:app --port 8001 --reload

# 터미널 2 — 프론트엔드 (변경사항 즉시 반영)
cd frontend
npm install
npm run dev

브라우저에서 http://localhost:5173 접속

---

백업

파일 저장 시 자동으로 백업이 생성됩니다. 백업 위치: ~/.hanes/backups/ 최대 10개 보관 (오래된 것부터 자동 삭제)

---

상태 표시

우측 상단의 상태 배지:

상태	의미
🟢 connected	백엔드 연결됨, 파일 변경 실시간 감지 중
🟡 connecting	연결 시도 중
🔴 disconnected	백엔드 연결 끊김 (hanes 재실행 필요)