Claude Code 설정을 관리하는 터미널 사용자 인터페이스(TUI) 애플리케이션

Claude Code 설정 파일(~/.claude.json)을 관리하기 위한 모던한 터미널 사용자 인터페이스(TUI) 애플리케이션입니다.
직관적인 계층적 인터페이스를 통해 MCP 서버, 프로젝트 및 대화를 간편하게 관리할 수 있습니다.

계층적 보기 (Hierarchical View): 트리 구조에서 전역 및 프로젝트 수준의 MCP 서버를 탐색합니다.
추가, 편집, 삭제 (Add, Edit, Delete): MCP 서버 구성을 위한 전체 CRUD(Create, Read, Update, Delete) 작업을 지원합니다.
서버 복사 (Copy Servers): 시각적 클립보드 추적 기능을 통해 서버 구성을 빠르게 복제할 수 있습니다.
서버 이동 (Move Servers): 서버를 전역 범위와 프로젝트 간에 이동시킬 수 있습니다.
다중 범위 지원 (Multi-Scope Support): 전역 및 프로젝트별 서버 모두를 관리할 수 있습니다.
민감 값 마스킹 (Sensitive Value Masking): API 키와 비밀값은 기본적으로 마스킹 처리되며 (V를 눌러 토글 가능) 합니다.

프로젝트 브라우저 (Project Browser): 서버, 대화 및 히스토리 개수를 포함하여 모든 Claude Code 프로젝트를 볼 수 있습니다.
실제 대화 관리 (Real Conversation Management): 파일 시스템에서 실제 .jsonl 대화 파일을 탐색하고, 세부 정보를 보고, 삭제할 수 있습니다.
대화 통계 (Conversation Statistics): 각 대화에 대한 메시지 수, 파일 크기, 그리고 나이를 확인할 수 있습니다.
대화 정리 (Conversation Cleanup): 전체 메타데이터 가시성을 통해 오래된 대화를 삭제할 수 있습니다.
히스토리 관리 (History Management): 프로젝트 간의 히스토리 항목을 보고, 삭제하고, 이동시킬 수 있습니다.
프로젝트 구성 (Project Organization): 각 프로젝트에 어떤 MCP 서버가 설정되어 있는지 확인할 수 있습니다.

자동 백업 (Automatic Backups): 저장하기 전에 타임스탬프가 찍힌 백업 파일을 생성합니다.
실행 취소/다시 실행 시스템 (Undo/Redo System): Ctrl+Z / Ctrl+Y를 통해 최대 50개 액션까지 전체 실행 취소/다시 실행을 지원합니다.
JSON 유효성 검사 (JSON Validation): 구성이 항상 유효한 상태인지 확인합니다.
롤백 지원 (Rollback Support): 필요할 경우 백업에서 쉽게 복원할 수 있습니다.
비파괴적 작업 (Non-destructive Operations): 삭제 전에 사용자에게 확인을 요청합니다.
오류 로깅 (Error Logging): 내보내기 기능이 있는 영구적인 오류 로그를 제공하며 (l을 눌러 보기 가능) 합니다.

환경 변수 지원 (Environment Variable Support): ${VAR} 형식의 환경 변수를 처리할 수 있습니다.

서버 설정의 구문(syntax) 지원
HTTP/SSE 서버: stdio, HTTP 및 SSE 서버 유형을 지원하며 헤더(headers)도 지원합니다.
대용량 파일 처리: 대용량 설정 파일을 효율적으로 관리합니다 (여러 MB 크기의 파일 처리 가능).
시각적 탐색: 포커스 관리가 가능한 직관적인 트리 기반 탐색 기능을 제공합니다.
시각적 변경 표시: 저장되지 않은 변경 사항은 제목 표시줄의 * 및 주황색 '저장' 버튼으로 확인할 수 있습니다.
향상된 클립보드: 서버와 기록(history)을 복사/붙여넣기 할 때 시각적인 상태 추적이 가능합니다.

pip install claude-code-config

git clone https://github.com/joeyism/claude-code-config.git
cd claude-code-config
pip install -e .

TUI 애플리케이션 실행:

claude-config
# 또는 짧은 별칭 사용
ccm

↑/↓
또는 j/k
: 트리 탐색(Navigate tree)
Enter
또는 Space
: 트리 노드 확장/축소(Expand/collapse tree nodes)
Right/Left
: 노드 확장/축소(Expand/collapse nodes)
a
: 새 MCP 서버 또는 기록 항목 추가(Add new MCP server or history item)
e
: 선택된 서버 또는 기록 항목 편집(Edit selected server or history item)
d
: 선택된 항목 삭제 (서버, 대화 또는 기록)(Delete selected item)
c
: 선택된 서버 또는 기록 항목을 클립보드에 복사(Copy selected server or history item to clipboard)
p
: 클립보드에서 붙여넣기(Paste from clipboard)
m
: 서버 또는 기록 항목을 다른 프로젝트로 이동(Move server or history item to different project)
v
: 붙여넣은 내용 상세 보기(View pasted content details)

s
: 변경 사항 저장(Save changes)
r
: 디스크에서 다시 로드(Reload from disk)
q
또는 Ctrl+C
: 종료 (저장되지 않은 변경 사항이 있을 경우 확인 메시지 표시)

V
: 민감한 값 마스킹 토글 (비밀 정보 보기/숨기기)(Toggle sensitive value masking)
Ctrl+Z
: 마지막 작업 실행 취소(Undo last action)
Ctrl+Y
: 작업 다시 실행(Redo action)
u
: 실행 취소/다시 실행 기록 보기(View undo/redo history)
l
: 오류 로그 보기(View error log)
x
: 클립보드 지우기(Clear clipboard)
?
: 도움말 표시(Show help)

이 도구는 다음을 포함하는 ~/.claude.json 파일을 관리합니다:

mcpServers: 전역 MCP (Model Context Protocol) 서버 설정
projects: 프로젝트별 설정. 다음을 포함합니다:

• mcpServers: 프로젝트 수준의 MCP 서버 설정
• conversations: 각 프로젝트의 대화 기록 (참고: 실제 대화 내용은 ~/.claude/projects/에 있는 .jsonl 파일입니다.)
  history: 빠른 접근을 위한 사용자 입력 기록

• 다양한 프로젝트별 설정
  기타 설정: 다양한 Claude Code 설정 (유지됨)

Claude 설정
├── Global Servers (1)
│ └── 📡 terraform-cloud-mcp
...

Stdio 서버:

{
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-example"],
...

HTTP 서버:

{
"type": "http",
"url": "https://api.example.com/mcp",
...

# 저장소 클론하기
git clone https://github.com/joeyism/claude-code-config.git
cd claude-code-config
...

# 전체 테스트 스위트 실행
pytest tests/
# 또는 빠른 검증 테스트 실행
...

black claude_code_config/
ruff check claude_code_config/

~/.claude.json 파일은 수백 개의 프로젝트와 서버가 포함될 경우 여러 메가바이트로 커질 수 있습니다. 수동 편집은 다음과 같은 문제가 발생합니다:

오류를 일으키기 쉬움: JSON 구문을 깨뜨리기 쉽습니다.
어려움: 프로젝트 전반에 걸쳐 특정 서버를 찾기 어렵습니다.
위험함: 자동 백업 기능이 없습니다.
시간 소모적: 크고 중첩된 구조를 탐색하는 데 시간이 오래 걸립니다.

Claude Code Config는 다음 기능을 통해 이러한 문제를 해결합니다:

• 시각적인 트리 탐색
• 유효성 검사 및 실행 취소/다시 실행 기능이 있는 안전한 편집
• 자동 백업
• 빠른 검색 및 필터링
• 파일 크기 추적을 통한 대화 관리

오래된 대화 정리: 대화를 삭제하여 공간을 확보할 수 있습니다 (파일 크기 정보 및 총 통계와 함께)
히스토리 항목 관리: 프로젝트 간 히스토리 항목을 보거나, 삭제하거나 이동할 수 있습니다 (실행 취소 지원 포함)
MCP 서버 구성: 서버를 글로벌 범위와 프로젝트 범위 사이로 이동시킬 수 있습니다
서버 설정 복사: 새 프로젝트를 위해 작업 구성을 복제할 수 있습니다 (클립보드 추적 기능 포함)
서버 사용 감사: 어떤 프로젝트가 어떤 MCP 서버를 사용하는지 확인할 수 있습니다
설정 안전하게 편집: 실행 취소/다시 실행 안전망을 갖추고 변경 사항을 적용할 수 있습니다
비밀 보호: API 키 노출 없이 설정을 탐색합니다 (자동 마스킹 기능)
대화 성장 추적: 대화 파일 크기를 모니터링하고 오래된 큰 대화를 정리할 수 있습니다.

실행 취소/다시 실행 시스템

• Ctrl+Z (실행 취소) 및 Ctrl+Y (다시 실행)를 통한 전체 실행 취소/다시 실행 기능 - 파괴적인 작업 전에 최대 50개의 이전 상태를 자동 스냅샷으로 저장합니다.
• u를 사용하여 실행 취소/다시 실행 기록을 볼 수 있습니다.

key - 저장/재로드 후 스마트 클리어링

• 실수로 인한 변경 사항에 대한 안전장치 제공

변경 사항을 위한 시각적 표시기 (Visual Indicators for Changes)

• 설정이 수정되면 제목 표시줄(Title bar)에 *가 표시됨 - 저장되지 않은 수정 사항이 있을 경우 부제목(Subtitle)에 "⚠ Unsaved changes"가 표시됨
• 변경 사항이 있으면 저장 버튼이 녹색에서 주황색으로 바뀌고 *를 표시함 - 어떤 수정 작업 후에도 자동 업데이트됨
• 명확한 시각적 피드백은 실수로 인한 데이터 손실을 방지함

향상된 클립보드 (Enhanced Clipboard)

• 상단 상태 표시줄(Status bar)에 클립보드 내용이 표시됨: 서버 또는 히스토리 항목
• 아이콘(📋)과 색상이 있는 메시지를 통해 시각적 피드백 제공
• 새 x 단축키를 추가하여 클립보드를 빠르게 지울 수 있음 - 상세 요약 정보 표시: "Server 'name' | Env: 2 vars | Headers: 1 items"
• 타입 인식 클립보드는 서버와 히스토리 항목을 구별함

영구 오류 로그 (Persistent Error Log)

• l 키를 눌러 포괄적인 오류 로그를 볼 수 있음 - 마지막 100개의 오류를 전체 상세 정보(메시지, 트레이스백, 컨텍스트)와 함께 저장함
• 기능: 오류 탐색, 파일로 내보내기, 로그 지우기, 심각도별 필터링
• 15초 타임아웃을 포함한 향상된 알림에 오류 로그 힌트가 포함됨
• 오류 정보를 잃지 않고 문제를 해결하는 데 도움을 줌

개선된 다이얼로그 (Improved Dialogs)

• 서버 이동(Move server) 다이얼로그가 이제 이동 히스토리(move history) 다이얼로그와 일관되게 변경됨
• 명확한 대상 선택 인터페이스 제공
• 프로젝트 간 항목을 이동할 때 더 나은 사용자 경험 제공

새 키보드 단축키 (New Keyboard Shortcuts):

Ctrl+Z: 마지막 작업 실행 취소(Undo)
Ctrl+Y: 다시 실행(Redo)
u: 실행 취소/다시 실행 히스토리 보기
l: 오류 로그 보기
x: 클립보드 지우기

추가된 파일 (Files Added):

claude_code_config/undo.py: 실행 취소/다시 실행 관리자 구현
claude_code_config/error_log.py: 오류 로깅 시스템
tests/test_phase1.py: 포괄적인 테스트 스위트

발견 (The Discovery)
이 도구는 원래 ~/.claude.json의 projects[path].conversations에서 대화 내용을 찾았지만, 이 필드는 항상 비어 있었습니다. Claude Code는 실제로는 ~/.claude/projects/<project-name>/에 .jsonl 파일을 사용하여 대화를 저장합니다. 많은 사용자가 수백 개의 대화 내용을 가지고 있었지만 볼 수도 관리할 수도 없었습니다!

구현된 솔루션:

• ConversationFile Model (conversations.py)

  • 파일 시스템에서 .jsonl 대화 파일을 파싱합니다. - 풍부한 메타데이터를 추출합니다: 제목(첫 사용자 메시지 기준), 생성 날짜, 메시지 수, 파일 크기.
  • 나이("4 days ago")와 크기(KB/MB)에 대한 사람이 읽기 쉬운 포맷터를 제공합니다.
  • 실제 대화 파일을 삭제하는 기능을 지원합니다.

• ConversationScanner (conversations.py)

  • 시작 시 ~/.claude/projects/ 디렉토리를 자동으로 스캔합니다. - 대화를 프로젝트별로 그룹화하여 체계적으로 표시합니다.
  • 통계를 제공합니다: 총 대화 수, 프로젝트 수, 누적 크기.
  • 효율적인 스캐닝: 메타데이터 추출을 위해 처음 50줄만 읽습니다.
  • 대용량 대화 파일에 최적화된 성능을 제공합니다.

• Enhanced ConfigManager (config.py)

  • 실시간 파일 시스템 스캔을 위한 ConversationScanner를 통합했습니다.
  • 새로운 메서드: get_conversations(project_path)
    • 특정 프로젝트의 대화를 검색합니다.
  • 새로운 메서드: get_all_conversations()
    • 프로젝트별로 그룹화된 모든 대화를 가져옵니다.
  • 새로운 메서드: get_conversation_stats()
    • 포괄적인 통계를 가져옵니다.

• 업데이트된 TUI (tui.py)

  • 설정 파일 대신 파일 시스템에서 실제 대화를 로드합니다.
  • 트리 디스플레이는 대화 제목과 나이를 표시합니다: "💬 Implement user auth (4 days ago)".
  • 상세 패널에는 포괄적인 메타데이터가 표시됩니다:
    • 전체 제목
    • 대화 ID
    • 메시지 수
    • KB/MB 단위의 파일 크기
    • 사람이 읽기 쉬운 나이
    • 전체 파일 경로 위치

• 삭제 기능은 이제 실제 .jsonl 파일을 디스크에서 제거합니다. - UI 성능을 위해 프로젝트당 최대 50개의 대화를 표시합니다.

사용 방법:

대화 보기:

• claude-config를 실행합니다.

• 트리에서 원하는 프로젝트로 이동합니다.

• 프로젝트 노드를 확장하여 "Conversations (N)"을 확인합니다.

• 더 확장하여 제목과 나이가 있는 모든 대화를 봅니다.

• 대화를 선택하면 오른쪽 패널에 전체 세부 정보가 표시됩니다.

오래된 대화 삭제:

• 트리에서 대화를 선택합니다.
• d를 누릅니다.

삭제하려면 - 대화 제목을 보여주는 다이얼로그에서 삭제를 확인합니다.

• 이 .jsonl 파일은 파일 시스템에서 영구적으로 제거됩니다.

예시 통계:

• 테스트 결과 12개 프로젝트에 걸쳐 302개의 대화가 발견되었습니다.
• 총 크기: 대화 데이터 30.85 MB
• 최고 프로젝트: python-movie-maker (대화 86개 포함)

기술 상세 정보:

• 파일 형식: ~/.claude/projects/<프로젝트 이름>/<대화 ID>.jsonl
• 파일의 각 줄은 JSON 객체입니다 (줄당 메시지 하나).
• 성능: 메타데이터를 위해 처음 50줄만 읽습니다.
• 표시 제한: UI에서 프로젝트별로 50개의 대화가 표시됩니다.

문제점:
MCP 서버를 탐색할 때, API 키, 토큰 및 비밀 값과 같은 민감한 값이 환경 변수와 헤더에 평문으로 노출되었습니다. 이는 어깨 너머로 보는 행위(shoulder surfing), 실수로 스크린샷을 찍는 것, 화면 공유, 클립보드 상태 노출 등 보안 위험을 야기했습니다.

해결책:

기본 마스킹 (Default Masking)

• 모든 환경 변수 및 헤더 값은 기본적으로 보안을 위해 마스킹됩니다.
• 상세 패널에 실제 값 대신 ****를 표시합니다. - 글로벌 및 프로젝트 범위 서버 모두에 자동으로 적용됩니다.
• 마스킹은 앱 실행 시마다 활성화 상태로 재설정됩니다 (세션 기반 보안).

가시성 토글 (Toggle Visibility)

• 대문자 V를 누르면 마스킹을 임시로 켜거나 끌 수 있습니다. -

• 상태 표시줄에 민감한 데이터가 노출되지 않음, 복사 시에도

• 화면 공유 중 우발적인 노출을 방지함

시각적 지표 (Visual Indicators)

[*****]

값(values)이 마스킹된 경우 표시되는 지표 (기본값)[SHOWN]

값이 보이는 경우 나타나는 지표 - 상세 패널에 토글 지침과 함께 표시됨

• 색상 코딩 알림 (마스크된 정보는 info, 보이는 값은 warning)

편집 양식 동작 (Edit Form Behavior)

• 서버를 편집할 때 (e 키 누름), 양식은 항상 실제 마스킹되지 않은 값을 보여줌 - 설정 변경을 편집하고 저장하는 데 필수적임
• 보안을 위해 브라우징 뷰에서만 마스킹 사용
• 편집 양식은 값에 대한 전체 접근 권한을 가지고 독립적으로 작동함

보안 이점 (Security Benefits):

• 기본적으로 안전한 자세 유지 (시작 시 마스킹)
• 어깨 너머로 훔쳐보는 행위(shoulder surfing)와 무단 열람 방지
• 스크린샷 및 화면 녹화에 안전함
• 데모 및 화면 공유 세션 중 보호됨
• 세션 기반: 보안 상태로 자동 초기화

구현 (Implementation):

• tui.py에서 7개 위치 수정