CLI & SDK

에이전트가 일하다 판단이 필요한 지점에 닿으면 당신 폰에 묻는다. 버튼을 누르거나 답을 입력하면 그 답이 살아 있는 세션으로 돌아가고, 에이전트는 하던 일을 계속한다.

@hwip/cli는 그 왕복의 터미널 쪽이다:

• HwipHook SDK — 네이티브 fetch, 런타임 의존성 없음. 푸시 전송·조회·해제.
• hwip CLI — 10개 에이전트를 한 명령으로 설정하고, 푸시를 보내며, hwip으로 띄운 에이전트 세션에 Hwip 앱이 입력을 넣을 수 있게 해주는 상주 listener를 띄운다(16개 에이전트 지원).

빠른 시작

CLI를 전역 설치하고 setup을 실행한다:

npm install -g @hwip/cli
hwip install

새 머신에서 hwip install은 브라우저 로그인을 연다. 웹앱이 API 키와 hook을 한 쌍으로 발급하고 CLI가 ~/.hwip/config.json에 기록한다. 복사·붙여넣기가 없다. 그다음 감지된 에이전트마다 rules·hooks·MCP를 설치한다.

다시 실행해도 안전하다. 저장된 로그인은 손대지 않고 재사용하므로, 재실행은 에이전트 연동만 갱신한다. 계정을 바꾸려면 hwip install --relogin이 새 로그인을 강제한다.

같은 계정으로 로그인한 Hwip 앱도 필요하다. 푸시와 질문은 읽을 앱이 있어야 하므로, 로그인한 앱이 없으면 hwip notify와 hwip ask는 아무것도 보내지 않고 그렇다고 알려준다. 폰 쪽 설정은 시작하기를 본다.

npx 대신 전역 설치를 쓰는 이유

앱으로 세션을 조종하는 hwip cc는 hwip이 PATH에 있어야 하고, 이때 설치되는 에이전트 hook은 $(command -v hwip || npx …) 형태로 풀린다. 전역 바이너리는 모든 알림마다 발생하는 npx 콜드 스타트를 건너뛴다.

폰 조종 없이 알림만 쓸 거라면 npx @hwip/cli install이 전역 바이너리를 건너뛰는 가벼운 대안이다(hwip cc도 함께 빠진다).

설치 변형

# 브라우저가 없는 헤드리스 머신: 다른 머신의 ~/.hwip/config.json 에서 자격 증명을 붙여넣는다
hwip install --key ak_... --hook hook_...

# 대화형 에이전트 선택 건너뛰기
hwip install --only claude,cursor

# 계정 전환 — 저장된 로그인 위에 새 브라우저 로그인을 강제
hwip install --relogin

# 에이전트 재설치 없이 자격 증명만 갱신. `hwip install`을 이미 한 번 돌렸다고 가정하며,
# 이것만으로는 에이전트에 MCP를 연결하지 않는다.
hwip login

첫 푸시 보내기

hwip notify --title "Deploy done" --body "v2.1.0 shipped"

설치 후에 일어나는 일

hook은 설정된 에이전트의 모든 세션에서 동작한다. hwip cc는 폰 조종 브리지일 뿐 알림 스위치가 아니다.

Claude Code에서는 턴마다 보내는 일상 푸시가 꺼진 채 시작한다. 기본값이 quiet이다. 터미널에서 자리를 비운 사이에는 끝난 턴이 여전히 푸시된다. /hwip-mode normal은 프로젝트의 일상 푸시를 켜고, /hwip-mode loud는 매 턴 푸시하며, /hwip-mode mute는 프로젝트를 완전히 조용하게 하고, /hwip-mode는 현재 적용 중인 값을 보여준다. 음소거와 푸시 모드를 본다.

~/.hwip/config.json이 유일한 정본이다. CLI·MCP 서버·플러그인 hook·listener가 모두 이 파일을 읽는다. 일반적인 설정에는 HWIP_API_KEY 같은 환경 변수가 필요 없다. 환경 변수는 두 번째 계정이나 CI를 위한 오버라이드로 존재한다.

지원 에이전트

hwip install이 아래를 자동으로 감지해 설정한다:

에이전트별 설정 페이지: Claude Code, Codex, Gemini CLI, pi, OpenCode.

hwip listener를 통한 원격 조종은 더 넓다. hwip <에이전트> 래퍼로 이름 붙은 tmux 세션 안에서 돌릴 수 있는 16개 에이전트가 대상이다. hwip install이 MCP·rules·hook을 연결하는 건 위 열 개뿐이라, 나머지 래퍼 에이전트(Kimi, Grok, Antigravity, Qwen, Auggie, Kilo, Kiro, Droid, Hermes, Cursor의 터미널 에이전트)는 앱에서 접근할 수 있을 뿐 그 이상은 없다. 원격 조종을 본다.

요구 사항

• Node.js 20.17+, 22.13+ 또는 23.5+ (네이티브 fetch 사용).
• tmux — hwip cc / codex / gemini 등 래퍼와 hwip listener에 필요하다. hwip install이 tmux를 확인하고, macOS에 Homebrew가 있으면 brew install tmux 실행을 제안한다. tmux는 Windows 빌드가 없어 Windows에서는 WSL이 필요하다.
• HwipHook SDK는 런타임 의존성이 없다. CLI가 쓰는 의존성 중에는 대화형 hwip install 선택기용 @inquirer/prompts, listener의 WebSocket 구독용 ws, 주석이 든 에이전트 설정 파일 편집용 jsonc-parser가 있다.