Creatree

Claude Code를 PTY로 래핑하여 Git worktree 지원 및 멀티 모드 인터페이스를 제공하는 TUI/CLI 도구.

주요 기능

• Git Worktree 관리: 워크트리 생성, 삭제, 아카이브를 UI에서 처리
• 세션 관리: 새 세션, 기존 세션 계속 옵션
• 7가지 모드: 프로젝트 선택, 워크트리 선택/생성/관리, Claude, Parent, Shell
• Shell 세션 유지: Claude 작업 중 별도 쉘 세션 유지
• 원격 접속: 데몬 모드로 브라우저/모바일에서 Claude 세션 접속
• PTY 래핑: Claude Code 업데이트에 영향받지 않는 블랙박스 방식

목차

• 설치
• 빠른 시작
• 명령어
• 모드 시스템
• 키 바인딩
• 설정
• 워크트리 셋업
• 데몬 (원격 접속)
• 아이콘 설명
• 플랫폼별 참고사항
• 개발
• 라이선스

설치

요구사항

| 항목 | 최소 버전 | 비고 | |------|----------|------| | Node.js | 18.0.0 | node -v로 확인 | | Git | 2.18.0 | worktree 기능 사용 | | Claude Code CLI | - | claude 명령어가 PATH에 있어야 함 |

node-pty 빌드 요구사항

creatree는 터미널 에뮬레이션을 위해 node-pty 네이티브 모듈을 사용합니다.

macOS

xcode-select --install

Ubuntu/Debian

sudo apt-get install build-essential python3

Fedora/RHEL

sudo dnf groupinstall "Development Tools"
sudo dnf install python3

Windows

npm install --global windows-build-tools

npm 설치 (권장)

npm install -g creatree

소스에서 빌드

git clone https://github.com/creatrip/creatree.git
cd creatree
npm install
npm run build
npm link

설치 확인

creatree --version

빠른 시작

1. Git 프로젝트 디렉토리로 이동

cd ~/my-project

2. creatree 실행

creatree

워크트리 선택 화면이 나타납니다. 화살표 키로 선택하고 Enter로 Claude를 시작합니다.

3. 현재 디렉토리에서 바로 시작

creatree .

워크트리 선택 없이 현재 디렉토리에서 바로 Claude가 시작됩니다.

명령어

기본 실행

creatree                     # 워크트리 선택 화면
creatree .                   # 현재 디렉토리에서 Claude 실행 (새 세션)
creatree <worktree-name>     # 지정한 워크트리에서 Claude 실행 (세션 계속)

옵션

| 옵션 | 설명 | |------|------| | -c, --continue | 기존 세션 계속 | | -n, --new | 새 세션 시작 | | -V, --version | 버전 표시 | | -h, --help | 도움말 표시 |

creatree . -c               # 현재 디렉토리에서 기존 세션 계속
creatree . -n               # 현재 디렉토리에서 새 세션 시작
creatree feature-1 -c       # 워크트리에서 기존 세션 계속
creatree feature-1 -n       # 워크트리에서 새 세션 시작

서브 명령어

creatree list               # 워크트리 목록 출력
creatree prune              # 고아 디렉토리 정리 (대화형)
creatree config             # 현재 설정 표시

데몬 명령어

creatree daemon start       # 데몬 시작
creatree daemon stop        # 데몬 종료
creatree daemon stop -f     # 활성 세션 있어도 강제 종료
creatree daemon status      # 데몬 상태 확인
creatree daemon restart     # 데몬 재시작
creatree daemon restart -f  # 강제 재시작

모드 시스템

creatree는 7가지 모드로 구성됩니다.

모드 목록

| 모드 | 설명 | 화면 | |------|------|------| | project-select | 최근 프로젝트 선택 (git 저장소 아닌 곳에서 실행 시) | 메인 | | worktree-select | 워크트리 선택 화면 | 메인 | | worktree-create | 새 워크트리 생성 (브랜치명 입력) | 메인 | | worktree-manage | 워크트리 관리 (아카이브, 삭제) | 메인 | | claude | Claude Code 실행 | 메인 | | parent | 액션 메뉴 (Shell, WebStorm 등) | Alternate | | shell | 대화형 쉘 (세션 유지) | Alternate |

모드 전환 흐름

┌──────────────────┐
│  project-select  │ ← git 저장소 아닌 곳에서 실행 시
└────────┬─────────┘
         │ Enter (프로젝트 선택 → 클립보드 복사)
         ▼
┌──────────────────┐
│ worktree-select  │◀────────────────────────────┐
└────────┬─────────┘                             │
         │ Enter/s        n              m       │
         ▼                ▼              ▼       │
┌────────────────┐ ┌─────────────┐ ┌──────────┐  │
│     claude     │ │   create    │ │  manage  │  │
└────────┬───────┘ └─────────────┘ └──────────┘  │
         │                                       │
         │ Ctrl+Shift+\ 또는 Ctrl+Shift+]/[      │
         ▼                                       │
┌────────────────┐                               │
│     parent     │───────────────────────────────┘
└───────┬────────┘        q/Esc
        │ s
        ▼
┌────────────────┐
│     shell      │──── exit/Ctrl+D ───▶ claude
└────────────────┘

키 바인딩

프로젝트 선택 모드 (project-select)

git 저장소가 아닌 디렉토리에서 실행하면 최근 사용한 프로젝트 목록이 표시됩니다.

| 키 | 동작 | |----|------| | ↑ / ↓ | 프로젝트 선택 이동 | | Enter | 선택한 프로젝트 경로를 클립보드에 복사 (macOS) | | Esc | 종료 |

워크트리 선택 모드 (worktree-select)

| 키 | 동작 | |----|------| | ↑ / ↓ | 워크트리 선택 이동 | | Enter / s | 선택한 워크트리에서 Claude 시작 | | n | 새 워크트리 생성 | | m | 워크트리 관리 | | q | 종료 |

워크트리 생성 모드 (worktree-create)

| 키 | 동작 | |----|------| | 문자 입력 | 브랜치명 입력 | | Backspace | 마지막 문자 삭제 | | Enter | 워크트리 생성 | | Esc | 취소 |

워크트리 관리 모드 (worktree-manage)

| 키 | 동작 | |----|------| | ↑ / ↓ | 워크트리 선택 이동 | | Space | 선택/해제 (다중 선택) | | a | 선택한 워크트리 아카이브 토글 | | d | 선택한 워크트리 삭제 | | D | 선택한 워크트리 전체 삭제 | | q / Esc | 선택 화면으로 돌아가기 |

Claude / Shell 모드

| 키 | 동작 | |----|------| | Ctrl+Shift+\ | Parent 모드로 전환 | | Ctrl+Shift+[ | 이전 페이지로 전환 (claude → parent → shell) | | Ctrl+Shift+] | 다음 페이지로 전환 (shell → parent → claude) | | (기타) | 자식 프로세스(Claude/Shell)로 전달 |

참고: Ctrl+Shift+\는 Claude 모드에서 ultrathink 명령을 삽입하는 용도로도 사용됩니다.

Parent 모드

| 키 | 동작 | |----|------| | s | Shell 열기 (기존 세션 유지) | | x | Shell 종료 | | c | VSCode 열기 | | w | WebStorm 열기 | | t | 새 터미널 탭 열기 (macOS만) | | r | QR코드 표시/숨김 토글 | | Ctrl+Shift+\ | Claude / Shell 모드로 복귀 | | Esc | Claude 모드로 복귀 | | q | 워크트리 선택으로 돌아가기 |

설정

설정 파일 위치

| 파일 | 설명 | |------|------| | ~/.creatree/config.json | 프로젝트/워크트리 데이터 | | ~/.creatree/config.jsonc | 사용자 설정 (CLI 선택 등) | | ~/.creatree/logs/ | 디버그 로그 (7일 보존) |

사용자 설정 (~/.creatree/config.jsonc)

{
  // 사용할 CLI: "claude" 또는 "opencode"
  "cli": "claude",

  // 데몬 포트 (기본값: 1440)
  "daemonPort": 1440
}

CLI 옵션

| CLI | 명령어 | 비고 | |-----|--------|------| | claude | Claude Code | 기본값 | | opencode | OpenCode | Claude Code 대안 |

디렉토리 구조

~/.creatree/
├── config.json              # 프로젝트/워크트리 데이터
├── config.jsonc             # 사용자 설정
├── daemon.sock              # 데몬 IPC 소켓
├── daemon.pid               # 데몬 PID
├── daemon.pin               # 데몬 인증 PIN
├── {project-id}/            # 프로젝트별 워크트리 디렉토리
│   ├── feature-1/           # Git worktree
│   ├── feature-2/
│   └── ...
└── logs/                    # 디버그 로그
    └── YYYY-MM-DD.log

워크트리 경로 규칙

• 위치: ~/.creatree/{project-id}/{worktree-name}/
• 브랜치명의 슬래시(/)는 대시(-)로 변환
  • 예: feature/login → feature-login

워크트리 셋업

워크트리 생성 시 자동으로 실행할 스크립트를 정의할 수 있습니다.

설정 파일 (worktree.json)

프로젝트 루트에 worktree.json 파일을 생성합니다:

{
  "scripts": {
    "setup": "npm install && cp $WT_SOURCE_PATH/.env .env"
  }
}

환경변수

셋업 스크립트 실행 시 다음 환경변수가 주입됩니다:

| 변수 | 설명 | |------|------| | WT_SOURCE_PATH | 원본 프로젝트 경로 | | WT_PATH | 새 워크트리 경로 | | WT_NAME | 워크트리 이름 | | WT_BRANCH | 부모 브랜치명 |

셋업 예시

{
  "scripts": {
    "setup": "pnpm install && cp \"$WT_SOURCE_PATH/.env\" .env && cp -r \"$WT_SOURCE_PATH/.claude\" .claude"
  }
}

우선순위

1. worktree.json (있으면 사용)
2. conductor.json (폴백)
3. 둘 다 없으면 셋업 스킵

Conductor 호환성

Conductor 앱과 호환됩니다. conductor.json의 scripts.setup을 그대로 사용할 수 있습니다.

추가로 다음 환경변수도 주입됩니다:

| 변수 | 설명 | |------|------| | CONDUCTOR_ROOT_PATH | = WT_SOURCE_PATH | | CONDUCTOR_WORKSPACE_PATH | = WT_PATH | | CONDUCTOR_WORKSPACE_NAME | = WT_NAME | | CONDUCTOR_DEFAULT_BRANCH | = WT_BRANCH |

데몬 (원격 접속)

데몬을 실행하면 브라우저나 모바일에서 Claude 세션에 접속할 수 있습니다.

데몬 시작

creatree daemon start

출력 예시:

  ✓ 데몬 실행 중
  PIN: 1234
  URL: http://localhost:1440

접속 방법

1. 브라우저에서 표시된 URL 접속
2. PIN 입력하여 인증
3. 세션 목록에서 접속할 세션 선택

QR코드 접속

Parent 모드에서 r 키를 누르면 QR코드가 표시됩니다. 모바일에서 스캔하여 빠르게 접속할 수 있습니다.

Tailscale 연동

Tailscale이 설치되어 있고 실행 중이면, 자동으로 MagicDNS URL이 사용됩니다.

URL: http://your-machine.tail1234.ts.net:1440

외부 네트워크에서도 Tailscale VPN을 통해 접속할 수 있습니다.

데몬 관리

creatree daemon status      # 상태 확인
creatree daemon stop        # 종료 (활성 세션 있으면 거부)
creatree daemon stop -f     # 강제 종료
creatree daemon restart     # 재시작

웹 UI 페이지

| 경로 | 설명 | |------|------| | / | 메인 페이지 (세션 목록) | | /login.html | PIN 입력 페이지 | | /terminal.html | 터미널 뷰 | | /chat.html | 채팅 뷰 |

아이콘 설명

워크트리 상태

| 아이콘 | 의미 | |--------|------| | 🥑 | 원본 프로젝트 (Root) | | 🌱 | 새 워크트리 (1시간 미만) | | 🌿 | 일반 워크트리 | | 🪵 | 아카이브된 워크트리 | | 🍂 | 오래된 워크트리 (7일 이상) |

Git 상태

| 표시 | 의미 | |------|------| | ✓ | 깨끗함 (변경사항 없음) | | ●N | N개 변경사항 있음 |

플랫폼별 참고사항

macOS

모든 기능이 지원됩니다.

• 새 탭 열기 (t): iTerm2, Terminal.app 지원
• 클립보드 복사: pbcopy 사용
• VSCode: PATH에 code 명령어 필요 (VSCode에서 Cmd+Shift+P → "Shell Command: Install 'code' command in PATH")
• WebStorm: PATH에 webstorm 명령어 필요

Linux

대부분의 기능이 지원됩니다.

• 새 탭 열기: 미지원
• 클립보드 복사: 수동 복사 필요 (명령어만 표시)
• VSCode: PATH에 code 명령어 필요
• WebStorm: PATH에 webstorm 명령어 필요

Windows

기본적인 기능은 지원되나 일부 제한이 있습니다.

• 새 탭 열기: 미지원
• 클립보드 복사: 수동 복사 필요
• VSCode: 설치 시 PATH에 자동 추가됨
• node-pty: Windows Build Tools 설치 필요

제약사항

• TTY 필수: 터미널에서만 실행 가능 (파이프 입력 불가)
• 워크트리 내 실행 불가: 원본 프로젝트에서만 실행해야 함
• Claude CLI 필요: claude 또는 opencode 명령어가 PATH에 있어야 함
• Git 저장소 필요: 워크트리 기능 사용 시 git 저장소여야 함

개발

빌드

npm run build      # TypeScript 컴파일 + 웹 리소스 복사
npm run dev        # Watch 모드
npm run start      # dist/index.js 실행

린트/포맷

npm run lint       # Biome 검사
npm run lint:fix   # Biome 자동 수정
npm run format     # Biome 포맷팅

기술 스택

• TypeScript (strict mode)
• node-pty: PTY 생성 및 관리
• Commander: CLI 인자 파싱
• Hono: 웹 서버 (데몬)
• xterm-headless: 터미널 버퍼 관리
• string-width: 유니코드 너비 계산
• Biome: 린터/포매터

디버그 로그

로그 파일: ~/.creatree/logs/YYYY-MM-DD.log

라이선스

MIT