ictechgy · ictechgy · Jul 4, 2026 · Jul 4, 2026 · Jul 4, 2026 · Jul 4, 2026
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "understatus"
-version = "0.7.1"
+version = "0.7.2"
 edition = "2021"
 description = "A calm, unobtrusive macOS statusline addon for AI coding CLIs (Claude Code): CPU/memory/disk/network + session info with a quiet glyph theme."
 # macOS 전용 크레이트 (host_processor_info / sysctl / IOKit FFI 의존)

diff --git a/README.md b/README.md
@@ -300,7 +300,8 @@ understatus binary  (new process per call — no daemon, no state files, no lock
 |-----|--------|-------|
 | **Claude Code** | ✅ Full support | Custom `statusLine.command`, stdin JSON, `refreshInterval`, chain preservation, and Claude `rate_limits` rendering are supported. |
 | **lterm / cmux** | ✅ Native pill surface | `understatus render --source lterm --surface-format cmux-status` emits one-line JSON for cmux status pills. The plain lterm path can also use `--source lterm --oneline`. |
-| **Codex CLI (standalone)** | ⚠️ Manual/tmux path | Codex has a built-in `[tui].status_line` item list, not a Claude-style command hook. For tmux or shell status integrations, feed a small JSON payload to `understatus render --source codex --oneline`; understatus then enriches from `~/.codex` on a best-effort basis. |
+| **Codex CLI in cmux** | ✅ Sidebar pills via hooks | Codex still has a built-in `[tui].status_line` item list rather than a Claude-style command hook, so understatus pushes status to cmux's sidebar instead: `understatus cmux install-codex-hooks`, then trust the hook from Codex `/hooks`. |
+| **Codex CLI (standalone)** | ⚠️ Manual/tmux path | Outside cmux, Codex remains manual/tmux: feed a small JSON payload to `understatus render --source codex --oneline`; understatus enriches from `~/.codex` on a best-effort basis. |
 | **Gemini CLI** | ⏳ Forward-looking | `/footer` and `/statusline` expose built-in items only; custom command-backed statuslines are not supported by understatus today. |
 
 Examples:
@@ -312,10 +313,40 @@ printf '{"agent":"codex","cwd":"%s"}' "$PWD" | understatus render --source codex
 # lterm cmux native status pills (JSON, no ANSI)
 printf '{"source":"lterm","session":"codex","pane":"%%3","cwd":"%s","agent":"codex"}' "$PWD" \
   | understatus render --source lterm --surface-format cmux-status
+
+# Codex inside cmux: install sidebar status hooks.
+# After installing, open /hooks in Codex and trust the new understatus hook definitions.
+understatus cmux install-codex-hooks
+
+# Manual/debug cmux apply without installing hooks.
+printf '{"agent":"codex","cwd":"%s"}' "$PWD" | understatus cmux apply-codex --workspace "$CMUX_WORKSPACE_ID"
 ```
 
 For tmux status bars, prefer `color.mode = "none"` and let tmux apply its own `#[fg=...]` styling if raw ANSI SGR is not desired.
 
+### Codex + cmux sidebar hooks
+
+`understatus cmux install-codex-hooks` non-destructively merges understatus command hooks into
+`~/.codex/hooks.json`; existing hooks such as OMX are preserved. Codex treats user hooks as
+non-managed hooks, so new or changed hook definitions must be reviewed/trusted from Codex `/hooks`
+before they run.
+
+The hook target is `understatus cmux hook-codex`. It is intentionally quiet and fail-soft:
+
+- it emits neutral JSON (`{}`) so Codex hook stdout does not add prompt context or break `Stop`;
+- every installed hook handler has an explicit short timeout (`5` seconds);
+- it updates cmux with `cmux set-status` / `clear-status` only;
+- it never uses `cmux set-progress` because cmux progress is workspace-global and can clobber
+  between panes;
+- in hook mode, it only applies when a caller/environment target such as `CMUX_WORKSPACE_ID` is
+  present; it will not fall back to a focused workspace.
+
+Uninstall with:
+
+```bash
+understatus cmux uninstall-codex-hooks
+```
+
 ---
 
 ## Platform
@@ -346,7 +377,8 @@ macOS용 AI 코딩 CLI statusline 애드온입니다. CPU%, 메모리, 배터리
 - **비파괴 설치** — 기존 `statusLine.command`를 체이닝으로 보존하고 정확히 복원합니다.
 - **세션 캐시 격리** — 체인 출력·펄스 상태·네트워크 델타 캐시는 `session_id`별로 분리되어 여러 터미널을 동시에 열어도 값이 섞이지 않습니다. 배터리는 머신 전역.
 - **Claude rate-limit 표시** — Claude Code stdin에 `rate_limits`가 들어오면 5h/weekly 사용률과 리셋 카운트다운을 네트워크 호출 없이 표시합니다.
-- **lterm/cmux·Codex 경로** — `--source lterm --surface-format cmux-status`는 cmux pill JSON을 출력하고, `--source codex --oneline`은 tmux나 셸 status 연동 환경에서 `~/.codex`를 best-effort로 보강합니다.
+- **lterm/cmux·Codex 경로** — `--source lterm --surface-format cmux-status`는 cmux pill JSON을 출력합니다. Codex를 cmux 안에서 쓰는 경우 `understatus cmux install-codex-hooks`로 Codex hook을 설치하면 왼쪽 sidebar status pill이 자동 갱신됩니다. 독립 Codex/tmux 경로는 `--source codex --oneline`으로 `~/.codex`를 best-effort 보강합니다.
+- **hook 안전성** — Codex hook은 `{}`만 출력하고, 5초 timeout으로 fail-soft 동작하며, cmux에는 `set-status`/`clear-status`만 사용합니다. pane 간 전역 progress 충돌을 막기 위해 `set-progress`는 쓰지 않습니다.
 
 **설치**
 

diff --git a/homebrew/README.md b/homebrew/README.md
@@ -1,111 +1,93 @@
 # understatus Homebrew Formula
 
-This directory contains the Homebrew formula for understatus, staged here in the main repository. The actual tap that users install from is a **separate repository**: `ictechgy/homebrew-understatus`.
-
----
-
-## Directory layout
+This directory stages the Homebrew formula for understatus. Users install from
+the separate tap repository:
 
-```
-homebrew/
-  understatus.rb   <- the formula (staged here; must be copied to the tap repo)
-  README.md        <- this file
+```text
+ictechgy/homebrew-understatus
 ```
 
-The tap repo expects the formula at:
+The tap expects the formula at:
 
-```
+```text
 Formula/understatus.rb
 ```
 
 ---
 
-## Step-by-step: publishing a release
-
-### 1. Push the version tag
-
-Ensure `Cargo.toml` has `version = "0.1.0"`, then push the tag that triggers the release workflow:
-
-```sh
-git tag v0.1.0
-git push origin v0.1.0
-```
-
-The `.github/workflows/release.yml` workflow builds two release assets on GitHub Actions:
-
-| Asset | Runner |
-|---|---|
-| `understatus-0.1.0-aarch64-apple-darwin.tar.gz` | `macos-14` (Apple Silicon) |
-| `understatus-0.1.0-x86_64-apple-darwin.tar.gz` | `macos-13` (Intel) |
+## Current formula shape
 
-Each tarball contains a single executable named `understatus` at its root.
+`homebrew/understatus.rb` installs **prebuilt macOS binaries** from GitHub
+Releases:
 
-### 2. Obtain the SHA-256 of the source tarball
+- Apple Silicon: `aarch64-apple-darwin`
+- Intel: `x86_64-apple-darwin`
 
-After the tag is pushed (and GitHub has processed it), download the auto-generated source tarball and hash it:
+The formula does not build from source and does not require a Rust toolchain at
+install time. It is macOS-only because understatus uses macOS system APIs for
+CPU, memory, battery, disk, and network metrics.
 
-```sh
-curl -L https://github.com/ictechgy/understatus/archive/refs/tags/v0.1.0.tar.gz \
-  | shasum -a 256
-```
+---
 
-This prints a line like:
+## Publishing a release
 
-```
-a3f2...dead  -
-```
+1. Ensure all versioned files agree:
 
-Copy the hex digest (the part before the two spaces).
+   - `Cargo.toml`
+   - `Cargo.lock` if dependency metadata changed
+   - `npm/package.json`
+   - `homebrew/understatus.rb`
 
-### 3. Fill in the sha256 placeholder
+2. Tag and push the release:
 
-Open `homebrew/understatus.rb` and replace:
+   ```sh
+   git tag vX.Y.Z
+   git push origin vX.Y.Z
+   ```
 
-```ruby
-sha256 "REPLACE_WITH_SOURCE_TARBALL_SHA256"
-```
+3. Wait for `.github/workflows/release.yml` to publish both tarballs:
 
-with the actual digest:
+   ```text
+   understatus-X.Y.Z-aarch64-apple-darwin.tar.gz
+   understatus-X.Y.Z-x86_64-apple-darwin.tar.gz
+   ```
 
-```ruby
-sha256 "a3f2...dead"
-```
+4. Compute SHA-256 checksums:
 
-### 4. Copy the formula to the tap repository
+   ```sh
+   curl -L https://github.com/ictechgy/understatus/releases/download/vX.Y.Z/understatus-X.Y.Z-aarch64-apple-darwin.tar.gz \
+     | shasum -a 256
 
-The tap repository must exist at `ictechgy/homebrew-understatus` on GitHub (create it if it does not yet exist). Copy the updated formula into it:
+   curl -L https://github.com/ictechgy/understatus/releases/download/vX.Y.Z/understatus-X.Y.Z-x86_64-apple-darwin.tar.gz \
+     | shasum -a 256
+   ```
 
-```sh
-# From the understatus repo root
-cp homebrew/understatus.rb /path/to/homebrew-understatus/Formula/understatus.rb
+5. Update `homebrew/understatus.rb` with the new URLs and checksums.
 
-cd /path/to/homebrew-understatus
-git add Formula/understatus.rb
-git commit -m "feat: add understatus formula v0.1.0"
-git push origin main
-```
-
-### 5. Verify the tap works
+6. Copy the formula into the tap repository:
 
-```sh
-brew tap ictechgy/understatus
-brew install ictechgy/understatus/understatus
-understatus --version
-```
-
----
+   ```sh
+   cp homebrew/understatus.rb /path/to/homebrew-understatus/Formula/understatus.rb
+   cd /path/to/homebrew-understatus
+   git add Formula/understatus.rb
+   git commit -m "Update understatus to vX.Y.Z"
+   git push origin main
+   ```
 
-## For subsequent releases (e.g. v0.2.0)
+7. Verify the tap:
 
-1. Bump `version` in `Cargo.toml` to `0.2.0`.
-2. Update the `url` and `sha256` lines in `homebrew/understatus.rb` (new tag URL + new sha256).
-3. Repeat steps 1-5 above with the new version number.
+   ```sh
+   brew tap ictechgy/understatus
+   brew reinstall ictechgy/understatus/understatus
+   understatus --version
+   ```
 
 ---
 
 ## Formula design notes
 
-- **Builds from source** using `cargo install` via Homebrew's `std_cargo_args`. No prebuilt binary is bundled in this formula.
-- **macOS only**: the formula declares `depends_on :macos` because understatus uses macOS-exclusive APIs (`host_processor_info`, `sysctl`, IOKit FFI).
-- **Rust** is listed as a build-time dependency (`depends_on "rust" => :build`) and is not required at runtime.
-- The smoke test (`brew test understatus`) runs `understatus --version` and asserts the string `understatus` appears in the output.
+- The release tarball contains a single executable named `understatus`.
+- `bin.install "understatus"` installs that executable directly.
+- `depends_on :macos` documents the macOS-only runtime boundary.
+- `brew test understatus` checks that the installed binary reports the expected
+  crate name.
diff --git a/npm/README.md b/npm/README.md
@@ -1,8 +1,8 @@
 # understatus
 
-Claude Code용 macOS statusline 애드온.
+Claude Code와 Codex/cmux를 위한 macOS statusline 애드온입니다.
 
-CPU, 메모리, 세션 정보를 calm glyph 테마(○▁▄▆◆)로 표시합니다.
+CPU, 메모리, git/세션 정보를 calm glyph 테마(○▁▄▆◆)와 cmux sidebar pill로 조용하게 표시합니다.
 
 ## 설치
 
@@ -23,12 +23,24 @@ understatus install
 
 # Claude Code settings.json에서 제거
 understatus uninstall
+
+# Codex를 cmux 안에서 쓸 때 왼쪽 sidebar pill hook 설치
+understatus cmux install-codex-hooks
+
+# Codex hook 제거
+understatus cmux uninstall-codex-hooks
 ```
 
+Codex hook은 `~/.codex/hooks.json`에 비파괴적으로 병합됩니다. Codex가 non-managed hook
+승인을 요구하면 `/hooks`에서 understatus hook을 review/trust 해야 자동 갱신됩니다.
+hook stdout은 항상 neutral JSON(`{}`)이며, cmux에는 `set-status`/`clear-status`만 사용합니다.
+전역 progress 충돌을 피하기 위해 `set-progress`는 사용하지 않습니다.
+
 ## 요구 사항
 
 - macOS (arm64 / x64)
 - Node.js >= 16
+- Codex/cmux sidebar 연동을 쓰려면 로컬 `cmux` CLI와 Codex hooks 지원이 필요합니다.
 
 ## 링크
 

diff --git a/npm/install.js b/npm/install.js
@@ -22,7 +22,7 @@ const os = require('os');
 // 네이티브 바이너리를 받아오는 GitHub 릴리스 태그.
 // release/publish guard가 Cargo.toml, npm/package.json, 이 값, git tag를 lockstep으로
 // 검증합니다. 새 네이티브 릴리스를 낼 때 네 버전을 함께 올리세요.
-const VERSION = '0.7.1';
+const VERSION = '0.7.2';
 
 // CPU 아키텍처를 Rust 타겟 트리플로 매핑
 const archMap = {

diff --git a/npm/package.json b/npm/package.json
@@ -1,6 +1,6 @@
 {
   "name": "understatus",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Claude Code statusline addon for macOS — CPU, memory, session info with a calm glyph theme",
   "bin": {
     "understatus": "bin/understatus.js"