Hwip Docs
CLI & SDK

명령어 레퍼런스

hwip의 모든 명령, 플래그, 종료 코드, 환경 변수.

# 알림 보내기
hwip notify --title "Deploy done" --body "v2.1.0 shipped"

# 우선순위와 함께 보내기
hwip notify --title "Build failed" --priority high --url https://ci.example.com/123

# 내가 소유한 채널로 보내기
hwip channel list
hwip notify --channel Releases --title "v2.1.0" --body "shipped"

# 최근 푸시 목록
hwip list
hwip list --limit 10 --type note

# 푸시 해제
hwip dismiss push_01JXY...
hwip dismiss --all

# 현재 에이전트 세션 이름 바꾸기 (앱의 에이전트 목록에 표시)
hwip rename "Prod deploy"
hwip rename --clear                # 기본 이름으로 되돌림

# 다른 에이전트 세션에 메시지 입력 (같은 컴퓨터든 다른 컴퓨터든)
hwip agent send dev_listener_ab12cd34:hwip-api "Build is green — rerun the e2e suite"
hwip agent send hwip-api "…"       # 이름이나 별칭이 세션 하나를 가리키면 그대로 쓸 수 있다

# 이 컴퓨터에서 도는 에이전트 세션과 마지막 작업 보기
hwip agent list                    # KEY  AGENT  STATE  NAME; 스크립트용은 --json
hwip agent read hwip-api           # 마지막 3개 턴: 프롬프트, 에이전트 텍스트, 도구 이름

# 끝난 세션을 이 머신의 기록에서 지우기
hwip forget --ended

# 연결 테스트
hwip test

# 이름 붙은 tmux 세션에서 에이전트 실행 (listener가 닿을 수 있게)
hwip cc                       # claude
hwip codex                    # codex
hwip gemini                   # gemini
hwip pi                       # pi
hwip opencode                 # opencode
hwip cc --wt feat/x           # 새 git worktree + 브랜치에서 claude

# 타이머로 에이전트 세션 시작 (listener가 시작한다)
hwip schedule add cc --at 09:00 --days weekdays --prompt "Triage the open issues"
hwip schedule

# 상주 listener 실행 (포그라운드; 백그라운드로 돌리는 건 알아서)
hwip listener
hwip listener --ws-url wss://...   # 설정 덮어쓰기

# JSON 출력
hwip notify --title "Hello" --json

명령

명령설명
login브라우저 로그인: localhost 루프백으로 API 키와 hook을 ~/.hwip/config.json에 받아온다(--web-url, --timeout, --allow-host). 복사·붙여넣기가 없다. SSH에서는 URL과 콜백 포트를 포워딩하는 ssh -L 줄을 출력해, 내 컴퓨터의 브라우저로 로그인을 마칠 수 있게 한다
install (별칭: setup)한 명령 설정: 에이전트 감지, 설정 저장, rules·hooks·MCP 설치. 저장된 설정이 없으면 브라우저 로그인을 자동으로 연다. --only claude,cursor,…는 선택기를 건너뛴다(cc = claude, 모르는 id는 사용법 오류). 선택기를 띄울 터미널이 없으면 사용법 오류이므로 스크립트 설치에는 --key를 넘긴다
uninstall감지된 에이전트에서 Hwip을 제거하고 listener를 멈춘다(--dry-run, --purge). stdin이 터미널이면 먼저 묻고, --yes가 질문을 건너뛴다
verify감지된 에이전트 전반의 설치 상태를 점검한다(--ping은 실제 API 호출, --json은 JSON 객체 하나). tmux가 PATH에 있는지, listener가 도는지, 확정된 WebSocket URL과 그 출처, 마지막으로 실패한 푸시가 있으면 그것도 보고한다
check-updatenpm에 더 새로운 Hwip 버전이 있는지 확인
notify푸시 알림 전송. --channel <id 또는 이름>은 내가 소유한 채널로 보낸다
channel list내가 소유하거나 구독하는 채널을 yours 또는 following으로 표시해 나열한다. 소유자만 보낼 수 있다
ask폰에 질문하고 답을 기다린다. MCP hwip_ask 도구를 못 부르는 hook용이다. --title(필수), --body, --actions id:Label,…, --timeout <s>(기본 60), --accepts-exit. JSON 한 줄을 출력한다: {"answered":true,…} 또는 {"answered":false,"reason":"cancelled"|"timeout"|"error"}. 답이 오면 종료 코드 0, 아니면 1. 질문과 답은 봉인되어 오간다
ask-context [status|on|off|show] [--global]봉인된 질문이 싣는 git diff와 터미널 줄의 스위치. 끄지 않으면 켜져 있고, 프로젝트별 또는 --global로 끈다
file-view [status|on|off|log] [--global]앱이 이 컴퓨터의 세션 파일을 둘러보는 것의 스위치. 끄지 않으면 켜져 있다. log는 앱이 마지막으로 읽은 50건을 출력한다
list최근 푸시 알림 목록. 이 호스트가 열 수 없는 암호화 푸시는 [encrypted]로 보인다
dismiss <id>푸시 해제, 또는 --all
rename <name>앱에 표시되는 현재 에이전트 세션 이름을 설정한다. hwip cc 세션 안에서 실행하거나 --session <name>으로 지정한다. --clear로 초기화. tmux 세션과 이 머신의 listener 기기 id를 자동으로 찾는다(--device <id>로 다른 머신 지정)
agent send <target> <message…>폰에서 보낸 것처럼 다른 에이전트 세션(이 머신이든 다른 머신이든)에 메시지를 입력한다. target은 <deviceId>:<session> 키, 또는 세션 하나만 가리키는 이름·별칭이다. 메시지는 항상 봉인되며, 메시지로 -를 주면 stdin에서 읽는다. 종료 코드 0은 서버가 저장했다는 뜻이지 타이핑됐다는 뜻이 아니다
agent list [--json]이 머신에서 도는 에이전트 세션을 나열한다: 키, 에이전트, 상태(working, blocked, idle, unknown), 이름. 로컬 전용이라 서버도 API 키도 필요 없다
agent read <session> [--turns <n>] [--json]이 머신의 세션이 마지막에 한 일을 출력한다: 마지막 <n>개 턴(1–20, 기본 3). 프롬프트, 에이전트 텍스트, 대상이 달린 도구 이름만이고 도구 출력은 없다. 비밀처럼 보이는 문자열은 가리며 최선 노력이다. transcript 리더가 있는 에이전트(Claude Code, Codex, Gemini CLI, pi, OpenCode)에서 동작한다
send <target> <message…>agent send의 예전 이름
forget <session>끝난 세션을 이 머신의 기록에서 지워 앱의 지난 목록에서 사라지게 한다. 실행 중인 세션은 거부한다. --ended는 tmux에 더 이상 없는 기억된 세션을 전부 지운다
testAPI 키와 연결이 되는지 테스트 푸시를 보낸다. 기기가 실제로 울린다
trust [deviceId]이 컴퓨터의 키 지문과 고정된 기기를 보여준다. deviceId를 주면 계정이 지금 그 기기에 올려둔 키를 고정하고, --reset은 모든 고정을 푼다. 암호화 참고
cc · codex · gemini · cursor · hermes · pi · opencode · kimi · grok · agy · qwen · auggie · kilo · copilot · kiro-cli · droid에이전트를 hwip-<project> tmux 세션에서 실행한다. 그 프로젝트의 분리된(detached) 세션이 있으면 다시 붙고, 없으면 -2, -3, …을 붙인다. 첫 실행 때 백그라운드 listener를 자동으로 띄운다. 뒤따르는 인자는 에이전트로 그대로 넘어간다. --detach / --label <x> / --wt <name>은 인자 맨 앞에 둔다. cursor는 IDE가 아니라 cursor-agent를 실행한다
worktree [clean]--wt가 만든 git worktree와 각각을 붙잡고 있는 것을 나열한다. clean은 아무것도 붙잡지 않는 것을 지운다. --dry-run은 아무것도 지우지 않는다
schedule타이머로 에이전트 세션을 시작한다. schedule add <agent> (--at HH:MM | --every <N>m|<N>h) [-- <agent args…>], schedule [list](--json), schedule rm <id>. 옵션: --days, --prompt, --label, --wt, --max-runtime. 원격 조종 참고
sh앱이 입력할 수 있는 로그인 셸 hwip-<project>-sh를 열거나 다시 붙는다. 원격 조종 참고
mcp이 프로세스 안에서 MCP 서버를 stdio로 실행한다. 에이전트 MCP 설정이 띄우는 것이며 hwip install이 등록하므로 직접 칠 일은 없다
listener보통은 필요 없다. hwip cc가 자동으로 띄운다. 상주 데몬: WebSocket으로 구독하고, tmux 세션 목록을 보고하며, agent.command 푸시를 맞는 세션에 주입한다
remote-hook <agent>직접 실행하지 않는다. hwip install이 Codex·Gemini·pi에 연결하는 프롬프트 제출 hook이 이 명령을 불러 앱에서 주입된 메시지임을 표시한다. 원격 조종 참고

Notify 옵션

플래그설명
--title <text>푸시 제목 (기본값: "Task done")
--body <text>푸시 본문 (기본값: cwd가 git 저장소면 "<project> · <branch>", 아니면 "<project>")
--url <url>함께 보낼 URL
--type <type>푸시 타입: note, link, file, hook
--priority <p>우선순위: low, normal, high, urgent
--device <id>대상 기기 ID
--session <id>에이전트 세션 ID. 푸시가 그 세션 채팅에 묶인다(또는 HWIP_SESSION_ID 환경 변수)
--channel <id|name>내가 소유한 채널로 보낸다. 채널 푸시는 평문이며 --title 또는 --body가 필요하다. --auto, --device, --session과는 함께 못 쓴다. API 키에 channel:read와 push:write 스코프가 필요하다
--auto보내기 전에 푸시 게이트를 적용한다. /hwip-mode quiet·/hwip-mode loud 푸시 모드 다이얼을 따르며, 프로젝트별 또는 --global로 머신 전체에 적용된다. 게이트에 걸러진 푸시는 종료 코드 0으로 조용히 끝난다
--pushmode-default <m>프로젝트에 다이얼이 없을 때 --auto가 가정하는 모드: quiet(내장), normal, loud. 사용자가 정한 다이얼이 항상 이긴다
--marker <m>--auto용 Push Signal 마커: skip, push, high
--tools <n>, --nonreadonly <n>--auto 휴리스틱에 들어가는 턴의 도구 호출 수(기본값은 실제 작업이 있었다고 가정)

기본값은 hook이 부르는 경우에 맞춰 잡혀 있다. 예를 들어 Stop hook이 본문 없이 hwip notify --title "Task done"을 호출하면, IDE마다 래퍼를 짜지 않아도 어느 프로젝트의 어느 브랜치가 끝났는지 보인다. 끄려면 --body ""를 명시한다.

Listener 옵션

플래그설명
--ws-url <url>이번 실행에만 쓰는 WebSocket 엔드포인트. 지속 설정은 ~/.hwip/config.json의 wsUrl이다. ws:// 또는 wss:// URL이어야 한다
--key <api-key>API 키 (또는 HWIP_API_KEY 환경 변수)
--base-url <url>REST API 기본 URL (또는 HWIP_BASE_URL 환경 변수, 또는 ~/.hwip/config.json의 baseUrl)
--stop실행 중인 데몬을 멈추고 PID·버전 파일을 지운다
--restart멈춘 뒤 분리해서 다시 띄운다. 로그는 ~/.hwip/listener.log
--install-service · --uninstall-service · --service-status로그인할 때마다 listener를 시작한다(macOS는 launchd, Linux는 systemd 사용자 유닛). 원격 조종 참고
--no-keep-awakeAC 전원에서 Mac을 깨워 두지 않는다. 지속 설정: ~/.hwip/config.json의 "keepAwake": false
--no-turn-history앱의 기록용으로 세션 대화를 업로드하지 않는다. 지속 설정: ~/.hwip/config.json의 "turnHistory": false

listener는 지수 백오프와 지터로 1초에서 30초 상한까지 재연결한다. 인증 실패로 닫히면(4001, 4002, 4003) 무한 루프를 돌지 않고 종료 코드 3으로 끝난다. 키를 고치고 다시 시작한다.

List 옵션

플래그설명
--limit <n>푸시 개수 (1–20, 기본 5)
--type <type>푸시 타입으로 필터

전역 옵션

값을 받는 플래그는 다음 단어가 어떻게 생겼든 그것을 값으로 가져간다. 그래서 아무도 치지 않은 텍스트(승인할 명령, 모델의 메시지)가 hwip의 플래그를 설정할 수 없다. --는 hwip 플래그의 끝이다. hwip cc 같은 에이전트 서브커맨드 뒤의 단어는 손대지 않고 에이전트로 넘어간다.

플래그설명
--key <api-key>API 키 (또는 HWIP_API_KEY 환경 변수)
--base-url <url>API 기본 URL (또는 HWIP_BASE_URL 환경 변수)
--jsonJSON 형식으로 출력
--version버전 출력
--help, -h사용법 출력. 명령과 함께(hwip notify --help 또는 hwip help notify) 쓰면 그 명령의 사용법을 출력한다

음소거와 푸시 모드

둘 다 프로젝트 디렉터리의 cksum 해시를 키로 하는 상태 파일이며 ${XDG_STATE_HOME:-~/.local/state}/hwip 아래에 있다. Claude Code의 /hwip-mode mute, /hwip-mode quiet, /hwip-mode loud, /hwip-mode normal이 쓰고, CLI가 읽는다. 음소거는 모든 notify에서, 푸시 모드는 --auto에서 읽는다.

현재 프로젝트에 음소거 파일이 있으면 알림은 조용히 건너뛴다:

STATE_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/hwip"
HASH=$(printf '%s' "$PROJECT_DIR" | cksum | cut -d' ' -f1)

# 음소거 (Claude Code 플러그인의 /hwip-mode mute 가 만든다)
mkdir -p "$STATE_DIR" && touch "$STATE_DIR/muted-$HASH"

# 음소거 해제
rm -f "$STATE_DIR/muted-$HASH"

푸시 모드는 한 단어짜리 파일(quiet, loud, normal)이며 아래 순서로 해석하고 처음 걸리는 것이 이긴다:

순서파일설정하는 쪽
1$STATE_DIR/pushmode-<hash>/hwip-mode quiet · /hwip-mode loud · /hwip-mode normal
2/tmp/hwip-pushmode-<hash>옛 버전. 내가 소유한 파일일 때만 인정
3$STATE_DIR/pushmode-default어떤 다이얼이든 --global 형태. 머신 전체 기본값
4--pushmode-default <mode>호출하는 hook(설치된 hook은 normal을 넘긴다)
5(위에 아무것도 없음)quiet

4행이 상태 파일보다 아래에 있는 건 의도다. 플래그는 기본값을 정할 뿐, 사용자가 정한 다이얼을 덮어쓰지 않는다. 파일은 있는데 내용이 비어 있으면 5행이 아니라 normal로 해석한다.

음소거에 -default 형태가 없는 것도 의도다. 내용이 아니라 존재 여부가 키이기 때문에, 전역 음소거를 프로젝트 하나에서만 풀 방법이 없게 된다.

자리를 비운 동안의 quiet

quiet는 당신이 창을 보고 있다고 보고 일상 푸시를 막는다. 자리를 비우면 quiet에서도 notify --auto가 푸시를 보낸다(일반 우선순위). 붙어 있는 tmux 클라이언트가 없거나 입력이 HWIP_AWAY_SEC초(기본 300, 0은 감지 끔)보다 오래 없으면 자리를 비운 것으로 판단한다. 읽을 수 없는 것은 자리에 있는 것으로 친다.

CLI는 CLAUDE_PROJECT_DIR, CURSOR_PROJECT_DIR, WINDSURF_PROJECT_DIR을 확인하고 없으면 cwd로 대체한다.

마지막 푸시 실패

설치된 hook은 hwip notify … 2>/dev/null || true를 실행하므로 푸시가 실패해도 화면에 남는 게 없다. 그래서 hwip notify, hwip test, hwip install이 보내는 테스트 푸시는 마지막 실패를 ${XDG_STATE_HOME:-~/.local/state}/hwip/last-notify-failure.json에 기록하고, 푸시가 한 번 통과하면 지운다. kind는 no-key, auth, quota, rate-limit, client, server, timeout, network, no-app, unsealed 중 하나다. 메시지 텍스트·키·푸시 내용은 저장하지 않는다. hwip verify가 이를 Push delivery 아래에 보여준다.

종료 코드

코드의미
0성공
1일반 오류. ask가 답을 못 받음, verify에 실패한 점검이 있음, install에 실패한 단계가 있음, uninstall에 아니오라고 답함도 포함
2한도 초과. 사용법 오류도 포함(agent send, agent list, agent read, rename, forget, 잘못된 에이전트 서브커맨드 플래그, 선택기를 띄울 터미널이 없는 install)
3인증 실패 또는 API 키 없음 (listener 인증 종료 4001, 4002, 4003도 포함)
127tmux나 claude 같은 필수 외부 바이너리를 PATH에서 못 찾음

환경 변수

변수설명
HWIP_API_KEY--key가 없을 때 쓰는 API 키
HWIP_HOOK_IDMCP 서버의 양방향 도구(hwip_ask 등)용 hook ID. ~/.hwip/config.json의 hookId도 같은 역할
HWIP_BASE_URLAPI 기본 URL (기본값: https://api.hwip.app/v1). ~/.hwip/config.json의 키를 쓸 때는 그 파일의 baseUrl과 같은 origin이어야 하며, 아니면 HWIP_API_KEY도 함께 설정한다
HWIP_WS_URL사용 중단 예정. WebSocket 엔드포인트. ~/.hwip/config.json의 wsUrl이 우선하고, 파일에 없을 때만 읽으며, 앞으로 읽지 않게 된다
HWIP_TMUX_SOCKETlistener가 자동 탐색 대신 쓸 tmux 소켓 경로. tmux를 -L <name>이나 커스텀 -S <path>로 돌릴 때 쓴다
HWIP_SESSION_ID--session이 없을 때 쓰는 에이전트 세션 ID
HWIP_ASK_CONTEXT0, false, off, no는 한 번의 실행에서 질문 맥락을 끈다
HWIP_FILE_VIEWlistener 환경에서 0, false, off, no는 한 번의 실행에서 앱의 세션 파일 접근을 끈다
HWIP_AWAY_SECquiet가 자리 비움으로 치기까지의 입력 없는 시간(초). 기본 300, 0은 끔
HWIP_NO_UPDATE_CHECKhwip cc가 하루 한 번 하는 npm 업데이트 확인을 건너뛴다(CI가 설정돼 있어도 건너뜀)
HTTPS_PROXY · HTTP_PROXY · NO_PROXYAPI 호출과 listener 소켓을 프록시로 보낸다. 서비스로 설치된 listener는 셸의 변수를 보지 못하고 ~/.hwip/config.json의 "httpsProxy"·"httpProxy"·"noProxy"를 읽는다. 환경 변수가 설정 단위로 우선한다

이 페이지에서