명령어 레퍼런스
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-update | npm에 더 새로운 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에 더 이상 없는 기억된 세션을 전부 지운다 |
test | API 키와 연결이 되는지 테스트 푸시를 보낸다. 기기가 실제로 울린다 |
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-awake | AC 전원에서 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 환경 변수) |
--json | JSON 형식으로 출력 |
--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도 포함) |
| 127 | tmux나 claude 같은 필수 외부 바이너리를 PATH에서 못 찾음 |
환경 변수
| 변수 | 설명 |
|---|---|
HWIP_API_KEY | --key가 없을 때 쓰는 API 키 |
HWIP_HOOK_ID | MCP 서버의 양방향 도구(hwip_ask 등)용 hook ID. ~/.hwip/config.json의 hookId도 같은 역할 |
HWIP_BASE_URL | API 기본 URL (기본값: https://api.hwip.app/v1). ~/.hwip/config.json의 키를 쓸 때는 그 파일의 baseUrl과 같은 origin이어야 하며, 아니면 HWIP_API_KEY도 함께 설정한다 |
HWIP_WS_URL | 사용 중단 예정. WebSocket 엔드포인트. ~/.hwip/config.json의 wsUrl이 우선하고, 파일에 없을 때만 읽으며, 앞으로 읽지 않게 된다 |
HWIP_TMUX_SOCKET | listener가 자동 탐색 대신 쓸 tmux 소켓 경로. tmux를 -L <name>이나 커스텀 -S <path>로 돌릴 때 쓴다 |
HWIP_SESSION_ID | --session이 없을 때 쓰는 에이전트 세션 ID |
HWIP_ASK_CONTEXT | 0, false, off, no는 한 번의 실행에서 질문 맥락을 끈다 |
HWIP_FILE_VIEW | listener 환경에서 0, false, off, no는 한 번의 실행에서 앱의 세션 파일 접근을 끈다 |
HWIP_AWAY_SEC | quiet가 자리 비움으로 치기까지의 입력 없는 시간(초). 기본 300, 0은 끔 |
HWIP_NO_UPDATE_CHECK | hwip cc가 하루 한 번 하는 npm 업데이트 확인을 건너뛴다(CI가 설정돼 있어도 건너뜀) |
HTTPS_PROXY · HTTP_PROXY · NO_PROXY | API 호출과 listener 소켓을 프록시로 보낸다. 서비스로 설치된 listener는 셸의 변수를 보지 못하고 ~/.hwip/config.json의 "httpsProxy"·"httpProxy"·"noProxy"를 읽는다. 환경 변수가 설정 단위로 우선한다 |