Harp는 오픈 소스 Warp 터미널의 비공식 macOS 포크입니다. Warp의 터미널, AI, 클라우드 기능은 유지하면서 기존 탭 바를 장시간 실행되는 코딩 에이전트에 맞게 설계된 사이드바로 대체합니다.
Harp를 사용하면 여러 Claude Code 및 Codex 세션을 나란히 실행하고, 어떤 세션이 작업 중인지, 사용자의 입력을 기다리는지, 완료되었는지, 백그라운드에서 실행 중인지, 또는 보류되었는지를 빠르게 확인할 수 있습니다. Harp는 자체 서버를 운영하지 않으며, 상위 Warp 기능은 Warp에서와 마찬가지로 계속 Warp의 서버와 통신합니다.
Harp의 추가 기능
한눈에 보는 에이전트 상태
각 사이드바 행에는 Claude Code 또는 Codex 세션의 상태가 표시될 수 있습니다. 세션을 확인할 때까지 읽지 않음 표시가 유지되고, 점은 백그라운드 작업이 계속 실행 중임을 나타내며, 달 아이콘은 보류한 탭을 나타냅니다. Cmd+R을 사용하여 탭 이름을 변경할 수 있습니다.
영구 그룹
탭을 이름이 지정된 그룹에 넣어 프로젝트와 에이전트를 정리할 수 있습니다. tmux 통합이 활성화되면 Harp는 tmux 세션에 그룹과 순서를 저장합니다. 따라서 재시작 후에도 레이아웃이 유지되고 다른 tmux 클라이언트에서도 동일한 배치를 확인할 수 있습니다.
사용량 제한 링
사이드바 하단에는 각 제공업체에 대해 두 개의 링이 표시될 수 있습니다. 하나는 5시간 단위 창을, 다른 하나는 주간 제한을 나타냅니다. Harp는 사용자가 선택한 도구가 관리하는 로컬 JSON 파일에서 이 값을 읽습니다. 사용량 데이터를 직접 가져오지는 않습니다. 예상 파일 형식은 limit-rings 형식 문서를 참조하세요.
휴대폰 친화적인 tmux 세션
tmux에 연결된 세션에는 이름, 그룹, 읽음 상태, 비활성 플래그를 저장할 수 있습니다. SSH를 통해 휴대폰에서 시작하는 경우처럼 다른 곳에서 시작된 tmux 세션은 tmux 옵션 @warp_adopt를 1로 설정하여 Harp 탭을 요청할 수 있습니다.
Harp 설치
최신 macOS 빌드 설치
- GitHub Releases 페이지에서 최신 Harp 릴리스를 엽니다.
Harp-<version>.dmg파일을 다운로드합니다.- 디스크 이미지를 열고 Harp를 Applications 폴더로 드래그합니다.
Harp는 자체 번들 식별자 com.dominikmartn.Harp, URL 스킴 harp://, 설정 디렉터리 ~/.harp를 사용합니다. 따라서 이러한 리소스를 공유하지 않고 Warp와 나란히 실행할 수 있습니다.
소스에서 빌드
직접 Harp를 빌드하려면 macOS와 rust-toolchain.toml에 지정된 Rust 툴체인을 사용합니다. 저장소 루트에서 부트스트랩 스크립트를 한 번 실행합니다.
./script/bootstrap그런 다음 디버그 애플리케이션을 컴파일하고 실행합니다.
./script/run빌드 결과물은 target/debug/bundle/osx/Harp.app이며, 애플리케이션이 실행됩니다. macOS 실행 스크립트는 키체인에 있는 첫 번째 Apple Development ID로 애플리케이션에 서명하고, 해당 ID가 없으면 임시 서명을 사용합니다. 서명 및 공증이 가능한 릴리스 DMG를 만들려면 script/release_macos를 사용하고 도움말 출력을 참조하세요.
Harp 구성
Harp의 추가 통합 기능은 기본적으로 비활성화되어 있습니다. ~/.harp/settings.toml을 만들거나 편집한 다음 필요한 기능을 활성화합니다. Harp는 설정 파일이 변경되면 다시 로드합니다.
[integrations.limit_rings]
enabled = true
file = "~/.cache/limit-rings.json"
[integrations.tmux]
enabled = true사용량 제한 링 활성화
integrations.limit_rings.enabled를 true로 설정하고, integrations.limit_rings.file을 제공업체 사용량 값이 포함된 로컬 JSON 파일의 경로로 지정합니다. ~ 문자는 홈 디렉터리를 나타냅니다.
tmux 동기화 활성화
integrations.tmux.enabled를 true로 설정하면 tmux 동기화, 세션 도입, tmux 내부의 에이전트 감지가 활성화됩니다. Harp는 10초마다 tmux를 확인합니다.
tmux가 활성화되면 이름, 그룹, 순서, 읽음 플래그, 비활성 플래그, 도입된 세션을 동기화할 수 있습니다. 사용자 지정 동작이 필요한 경우 integrations.tmux.session_script에 이름 변경과 그룹 재지정을 처리하는 스크립트를 지정할 수 있습니다. 스크립트에는 다음 형식의 명령이 전달됩니다.
<script> rename <shell_pid> <group> <title>
<script> group <session_id> <old_group> <new_group>사이드바 및 에이전트 도구 모음 조정
appearance.vertical_tabs.full_tab_menu의 기본값은true입니다.false로 설정하면 탭 및 그룹 메뉴가 필수 작업만 표시하도록 줄어듭니다. Settings > Appearance > Tabs에서도 동일한 옵션을 사용할 수 있습니다.agents.third_party.should_render_cli_agent_toolbar의 기본값은false입니다.true로 설정하면 CLI 에이전트 세션 아래에 상위 도구 모음이 다시 표시됩니다.
타사 CLI 에이전트 도구 모음이 비활성화된 경우 프로젝트 설명에 따라 Claude Code의 플러그인 마켓플레이스에서 Warp 플러그인을 업데이트하세요.
코딩 에이전트와 함께 Harp 사용
- Harp를 열고 Claude Code 또는 Codex 작업 흐름에 사용할 세션을 만듭니다.
Cmd+R로 탭 이름을 변경하여 용도를 명확히 합니다.- 관련 세션을 프로젝트별 그룹과 같은 이름이 지정된 그룹에 배치합니다.
- 사이드바 상태 표시기를 확인하여 주의가 필요한 세션, 아직 작업 중인 세션, 완료된 세션을 식별합니다.
- 당장 필요하지 않은 세션은 보류합니다. Harp는 해당 세션에 달 아이콘을 표시합니다.
- 출력을 검토할 준비가 되면 읽지 않은 세션을 엽니다.
새 탭은 Cmd+T를 누르거나, 빈 사이드바 공간을 두 번 클릭하거나, 마우스 오른쪽 버튼 클릭 메뉴를 통해 만들 수 있습니다. 이 프로젝트에서는 검색 필드, 보기 옵션, 탭 구성 버튼을 비롯한 일부 탭 바 컨트롤을 의도적으로 제거했습니다.
다른 곳에서 시작한 세션 도입
다른 기기나 터미널에서 tmux 세션을 만든 경우, Harp에 해당 세션을 탭으로 도입하도록 요청할 수 있습니다. 해당 tmux 세션에서 다음을 실행하세요.
tmux set-option @warp_adopt 1tmux 통합을 활성화하면 Harp가 해당 세션을 추적하고 사이드바에 세션의 이름, 그룹 및 상태를 표시할 수 있습니다. SSH를 통해 시작한 작업을 계속할 때 유용하며, 휴대폰에서 시작한 작업도 포함됩니다.
Claude Code 백그라운드 작업 보고 연결
이 저장소에는 백그라운드 작업을 Harp에 보고하는 Claude Code 훅이 포함되어 있습니다. 통합 안내는 integrations/claude-code에서 확인할 수 있습니다. 백그라운드 활동이 사이드바에 표시되도록 하려면 해당 안내를 따르세요.
고급 개발 옵션
상태 변경 추적
에이전트 트랜스크립트에 대한 회귀 검사를 수행하려면 WARPOSS_STATUS_TRACE=1을 사용하여 디버그 빌드를 실행하세요. Harp는 상태 변경을 ~/Library/Logs/harp.log에 [status-check] 줄로 기록합니다.
실제 로그인 없이 실행
실행 시 WARPOSS_SKIP_LOGIN=1을 설정하면 테스트 사용자로 시작하고 인증된 요청이 실패하도록 만들 수 있습니다. 로그인하지 않는 자동화 실행을 위한 옵션입니다.
격리된 디버그 데이터 프로필 사용
디버그 빌드에서는 WARP_DATA_PROFILE=<name>을 설정하여 기본 프로필 위치 대신 ~/.harp-<name>에 설정과 데이터를 저장할 수 있습니다.
기여 내용 검증
변경 사항을 제출하기 전에 저장소의 사전 제출 검사를 실행하세요.
./script/presubmit이 검사는 포맷팅, Clippy 및 테스트를 실행합니다.
결론
Harp는 Warp 터미널을 장시간 실행되는 여러 Claude Code 및 Codex 세션을 관리하는 작업 공간으로 바꿔 줍니다. macOS 앱을 설치하거나 소스에서 빌드하고, 필요에 따라 tmux 및 limit-ring 통합을 활성화한 다음, 그룹과 상태 표시기를 사용하여 에이전트 기반 개발을 체계적으로 관리하세요. Harp는 비공식 Warp 포크이므로 Harp 관련 문제는 Warp가 아니라 해당 저장소에 보고하세요.