codex-agent-view 0.3.0 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/.codex-plugin/plugin.json +1 -1
  2. package/README.md +140 -58
  3. package/bin/codex-agent-view.mjs +6 -6
  4. package/package.json +1 -1
  5. package/skills/codex-agent-view/SKILL.md +9 -0
package/.codex-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codex-agent-view",
3
- "version": "0.3.0",
3
+ "version": "0.3.2",
4
4
  "description": "Read-only Codex app task snapshots with an optional local live monitor.",
5
5
  "author": {
6
6
  "name": "Junho Yoon",
package/README.md CHANGED
@@ -6,9 +6,38 @@ Codex Agent View는 공식 Codex 앱 안에서 여러 workspace의 active task
6
6
 
7
7
  ## 한국어 사용법
8
8
 
9
+ ### 빠른 시작: 설치 후에는 Codex 앱 안에서만 사용
10
+
11
+ 이 README와 package의 버전은 `codex-agent-view@0.3.2`다. Universal Plugins Directory 검색 등록은 아직 완료되지 않았으므로 **최초 설치만** 일반 터미널에서 진행한다.
12
+
13
+ ```bash
14
+ npm install --global codex-agent-view@0.3.2
15
+ codex-agent-view install
16
+ ```
17
+
18
+ 첫 번째 명령은 npm package를 설치하고, 두 번째 명령은 그 package를 Codex의 local plugin으로 명시적으로 등록한다. `npm install`만으로는 Codex 설정을 바꾸지 않으며 이 package에는 설정을 몰래 수정하는 `postinstall` script가 없다.
19
+
20
+ 설치 후에는 다음 순서만 따르면 된다.
21
+
22
+ 1. 설치 전에 Codex 앱이 열려 있었다면 앱을 완전히 종료한 뒤 다시 연다.
23
+ 2. Codex 앱의 **Plugins** 화면에서 `Codex Agent View`가 설치·활성화됐는지 확인한다.
24
+ 3. Hook 검토 화면이 표시되면 `hooks/hooks.json`과 `node "${PLUGIN_ROOT}/scripts/send-hook.mjs"` command를 확인하고 현재 definition을 직접 trust한다. 앱 버전이 hook 검토 UI를 제공하지 않을 때만 설치 과정의 일부로 interactive Codex CLI의 `/hooks`를 사용한다.
25
+ 4. 활성화와 hook 검토를 마친 뒤 Codex 앱에서 **새 task**를 만든다. 설치 전에 시작된 task의 과거 event는 재생되지 않는다.
26
+ 5. 새 task의 `@` 메뉴에서 `codex-agent-view`를 선택하고 다음처럼 요청한다.
27
+
28
+ > 현재 실행 중인 task와 subagent 상태를 보여줘.
29
+
30
+ 6. Hook 단위의 live 화면이 필요할 때는 같은 Codex 앱 task에서 다음처럼 요청한다.
31
+
32
+ > Codex Agent View live 화면을 앱 안에서 열어줘.
33
+
34
+ Plugin은 live 화면 요청 시 healthy local monitor를 내부적으로 재사용하거나 필요할 때 시작하고, 결과를 **Codex 내장 Browser**에서 연다. 일반 사용자는 `start`, `status`, `doctor`를 실행하거나 localhost 주소와 token을 복사할 필요가 없다. 외부 browser도 정상 사용 흐름에 포함되지 않는다.
35
+
36
+ 요약하면 설치는 터미널에서 한 번, 조회·상태 확인·live 화면 열기와 이후 사용은 Codex 앱 안에서 수행한다.
37
+
9
38
  ### 현재 상태
10
39
 
11
- 현재 source는 아직 배포되지 않은 `0.3.0` candidate이며 public npm `latest`는 `0.2.1`이다. 다음 구성은 source에 구현되어 있다.
40
+ 이 package version은 `0.3.2`다. 다음 구성이 package에 포함되어 있다.
12
41
 
13
42
  - 공식 Codex 앱의 내장 thread tools를 우선 사용하는 app-native active-task snapshot skill
14
43
  - `.codex-plugin/plugin.json`, local marketplace catalog, genuine Codex skill
@@ -23,14 +52,18 @@ Homebrew Codex CLI와 공식 앱에 포함된 embedded Codex executable에서는
23
52
 
24
53
  `0.2.1`은 부모 task lifecycle hook을 추가하고, `status`, `doctor`, 빈 UI가 “monitor 정상”과 “hook event 수신”을 구분하도록 개선한 patch다. 공식 Codex 앱 `26.727.40816`(`build 6067`)을 재시작하고 설치·활성화된 plugin `0.2.1`을 사용한 실제 E2E에서 task ID를 사전 등록하지 않아도 parent session 3개와 subagent 3개가 UI에 자동으로 나타났다. 실제 hook의 `SessionStart`, `UserPromptSubmit`, `Stop`, `SubagentStart`, `SubagentStop`, `PreToolUse`, `PostToolUse`, `PermissionRequest`가 sender → loopback monitor → UI 경로에 반영됐다. `SessionEnd` wiring은 포함돼 있지만 실제 공식 앱 event는 아직 관찰하지 않았으므로 호환 확인을 주장하지 않는다.
25
54
 
26
- `0.3.0` candidate의 팀장 E2E에서는 공식 앱 내장 thread tools로 `kyurasi-next-supabase`의 active task, workspace basename, title, description, explicit `inProgress` status, 최신 explicit agent commentary와 `subAgentActivity`를 확인했다. 완료 직후 list 결과가 explicit `idle`, `hasUnreadTurn: true`로 바뀌는 것도 확인했다. Skill은 이를 running/active와 분리한 `완료/확인 대기` 표시 그룹에 포함하지만, `idle + unread`만으로 완료 또는 성공을 추론하지 않는다. 별도의 hook/browser monitor에서는 실제 `SessionEnd`까지 관찰했다. 이는 source candidate 증거이며 `0.3.0` npm publish, tag, GitHub Release 또는 public artifact 설치 E2E를 뜻하지 않는다.
55
+ `0.3.0`의 팀장 E2E에서는 공식 앱 내장 thread tools로 `kyurasi-next-supabase`의 active task, workspace basename, title, description, explicit `inProgress` status, 최신 explicit agent commentary와 `subAgentActivity`를 확인했다. 완료 직후 list 결과가 explicit `idle`, `hasUnreadTurn: true`로 바뀌는 것도 확인했다. Skill은 이를 running/active와 분리한 `완료/확인 대기` 표시 그룹에 포함하지만, `idle + unread`만으로 완료 또는 성공을 추론하지 않는다. 별도의 hook/browser monitor에서는 실제 `SessionEnd`까지 관찰했다.
27
56
 
28
- Maintainer npm 2FA는 `auth-and-writes` mode로 활성화됐고 현재 `latest`인 `codex-agent-view@0.2.1`은 public npm registry에서 사용할 수 있다. npm publish와 별개인 Universal Plugins Directory 제출은 아직 완료되지 않아 directory 검색에는 나타나지 않는다.
57
+ Maintainer npm 2FA는 `auth-and-writes` mode로 활성화됐고 `codex-agent-view@0.3.1`은 검증된 이전 공개 릴리스다. npm publish와 별개인 Universal Plugins Directory 제출은 아직 완료되지 않아 directory 검색에는 나타나지 않는다.
29
58
 
30
59
  검증된 `0.2.0` 릴리스: npm `gitHead`와 annotated `v0.2.0` tag는 commit `00b62af56698ac875e39c7d1386905c157c3a7e8`로 일치하고, registry SRI/signature 및 tag source와 registry artifact의 21개 package file byte 일치를 확인했다. [GitHub Release v0.2.0](https://github.com/JunhoYoon95/codex-agent-view/releases/tag/v0.2.0)은 공개 상태다. 별도 npm provenance attestation은 선택 사항이며 이 릴리스에는 없다.
31
60
 
32
61
  공개 `0.2.1` patch: registry의 `latest`, version, `Apache-2.0` license, executable mapping, 21개 package file, unpacked size `144644`, npm `gitHead` `8d6a67c9aafa23f801235d747ff018d254378970`, shasum, exact SRI와 registry signature를 확인했다. Annotated `v0.2.1` tag는 같은 commit에 생성·push됐고 [GitHub Release v0.2.1](https://github.com/JunhoYoon95/codex-agent-view/releases/tag/v0.2.1)이 공개됐다. Clean cache exact-version `npx --version`을 통과했으며 registry tarball 21개 file과 tagged source가 byte-identical이다. 이 기기의 global install과 copied marketplace도 같은 registry tarball 21개 file과 byte-identical이고, CLI `0.2.1`, plugin installed/enabled, hook wiring 9종, 실제 session 자동 수신과 probe subagent의 running → stopped/UI 완료 반영을 검증했다.
33
62
 
63
+ 공개 `0.3.0`: 릴리스 당시 npm `latest`/version, `gitHead` `988132d0b525ee5e63f13a0d924810dd3f1bd93a`, shasum `08e2e5fa8c1133a1dcc3faae8f354535f9fc07b0`, exact SRI, registry signature, 21 files와 unpacked size `158.8 kB`를 확인했다. Annotated `v0.3.0` tag가 push됐고 [GitHub Release v0.3.0](https://github.com/JunhoYoon95/codex-agent-view/releases/tag/v0.3.0)이 공개됐다. 이 기기에 public exact `0.3.0`을 global reinstall해 plugin installed/enabled와 hook wiring 9종을 확인했다. Registry tarball과 global install의 artifact diff는 0이며 copied marketplace도 ownership marker 1개를 제외한 artifact file이 동일하다. Public install monitor에서 실제 hook, `workspace_label: codex-agent-view`, `PermissionRequest`, tool lifecycle과 probe subagent의 running → stopped 전환(`has_out_of_order_events: false`)을 확인했다.
64
+
65
+ 공개 `0.3.1`: npm version/당시 `latest` `0.3.1`, `gitHead` `c515ea28be201dc24d31e13bf465a38145050b69`, shasum `4405b183012c04e7b0bc265d4eb14bf85291dcd9`, integrity `sha512-8oF5uHqZobgPt75I2ymoq3/tx4Ab1YX/cvMPjaJHjV7zxVC5Dh318isoCdsKNi6emXEbiTIdxOgX7GcclyuP8A==`, 21 files를 확인했다. Annotated `v0.3.1` tag와 [GitHub Release v0.3.1](https://github.com/JunhoYoon95/codex-agent-view/releases/tag/v0.3.1)이 공개됐다. 이 기기에 exact `0.3.1`을 재설치했고 plugin `installed: true`, `enabled: true`를 확인했다. Public exact `0.3.1` app-only E2E 완료는 주장하지 않는다.
66
+
34
67
  ### 제품 경계
35
68
 
36
69
  Codex Agent View는 historical audit이나 session replay 제품이 아니라 현재 활동을 보여주는 live companion이다. Bounded in-memory state와 monitor 재시작 시 reset은 privacy와 단순한 failure boundary를 위한 의도된 완성 설계다. SQLite/영구 history는 누락된 요구사항이 아니다. 실제 사용자 요구가 입증될 때에만 retention, migration, deletion, privacy 비용을 별도 검토하는 명시적 opt-in 기능 후보로 취급한다.
@@ -44,24 +77,26 @@ Codex Agent View는 historical audit이나 session replay 제품이 아니라
44
77
 
45
78
  별도로 실행한 Codex `0.146` App Server의 `thread/list` fallback도 실제 확인했지만 현재 root/subagent가 모두 `notLoaded`로 나타나 공식 앱의 live running/completed 상태를 공유하지 않았다. Persisted parent ID, alias, depth 보강은 가능했지만 live 판별에는 채택하지 않았다. `0.3.0`의 primary snapshot은 이 별도 server가 아니라 현재 공식 앱이 직접 제공하는 내장 thread tools를 사용한다.
46
79
 
47
- ### npm, local browser UI, Plugins Directory가 각각 필요한 이유
80
+ ### npm, Codex 앱 live view, Plugins Directory의 역할
48
81
 
49
82
  - 공식 Codex 앱에서 plugin에게 `Show active tasks`라고 요청하는 것이 `0.3.0`의 primary UX다. 별도 monitor 실행이나 task ID 등록이 필요 없다.
50
- - npm은 plugin bundle과 optional local executable, hook sender, runtime, static UI를 사용자 machine에 배포하는 fallback 경로다.
51
- - Codex in-app Browser는 명시적으로 live view를 요청했을 때만 `127.0.0.1` monitor를 보여준다. 외부 website나 telemetry dashboard가 아니다.
83
+ - npm은 plugin bundle, 내부 hook sender/runtime과 static UI를 사용자 machine에 배포하는 최초 설치 경로다.
84
+ - Live view는 사용자가 앱 안에서 명시적으로 요청했을 때만 Codex 내장 Browser에 열린다. 외부 website나 telemetry dashboard가 아니다.
52
85
  - Universal Plugins Directory는 npm의 대체재가 아니다. 공개 directory의 in-app custom UI 경로는 public HTTPS MCP server와 domain verification이 필요해 local-only/no-external-server 원칙과 충돌한다. 현재는 별도의 listing/skills 제출 가능성만 검토하며, 심사·publish 전에는 Codex plugin 검색으로 설치할 수 있다고 안내하지 않는다.
53
86
 
54
87
  Hook event가 누락·중복·역순으로 올 수 있으므로 UI의 `unknown`, `stopped_without_start`, 빈 상태는 그대로 해석해야 한다. 빈 session 목록은 “이 monitor가 event를 관찰하지 못함”이며 “실행 중인 task가 없음”의 증거가 아니다.
55
88
 
56
89
  ### 공식 Codex 앱에서 사용 — 권장
57
90
 
58
- 1. Codex 앱에서 Codex Agent View plugin을 선택한다.
91
+ 이 절차는 위의 빠른 시작에서 설치와 활성화를 마친 뒤 **새 task**에서 수행한다. 별도 terminal이나 외부 browser는 사용하지 않는다.
92
+
93
+ 1. 새 task의 `@` 메뉴에서 `codex-agent-view`를 선택한다.
59
94
  2. `Show active tasks` 또는 “현재 active task와 subagent를 보여줘”라고 요청한다.
60
95
  3. Plugin은 여러 workspace의 running/active task와 explicit `idle + hasUnreadTurn` task를 조회한다. 후자는 별도 `완료/확인 대기` 그룹에 표시하되 완료·성공으로 단정하지 않는다.
61
96
  4. Workspace basename, 표시용 title, explicit status, 최신 explicit agent commentary와 `subAgentActivity`만 간결하게 보여준다.
62
97
  5. Prompt, preview, tool input/output, full workspace path와 internal thread ID는 기본 표시하지 않는다.
63
98
 
64
- Live hook detail이 필요할 때만 “Open the live Codex Agent View in the built-in Browser”라고 요청한다. Plugin은 healthy monitor를 재사용하며 tokenized localhost URL을 대화에 노출하지 않는다.
99
+ Live hook detail이 필요할 때만 앱 안에서 “Open the live Codex Agent View in the built-in Browser”라고 요청한다. Plugin은 healthy monitor를 내부적으로 재사용하거나 시작하며 tokenized localhost URL을 대화에 노출하지 않는다.
65
100
 
66
101
  ### 요구사항과 검증 범위
67
102
 
@@ -73,7 +108,7 @@ Live hook detail이 필요할 때만 “Open the live Codex Agent View in the bu
73
108
 
74
109
  | Runtime | 확인된 버전 | 확인 범위 |
75
110
  | --- | --- | --- |
76
- | 공식 Codex 앱 | `26.727.40816` (`build 6067`) | `0.3.0` source candidate app-native snapshot에서 active task/title/description/inProgress/commentary/subAgentActivity 확인; browser monitor에서 실제 `SessionEnd` 확인 |
111
+ | 공식 Codex 앱 | `26.727.40816` (`build 6067`) | `0.3.0` public release에서 app-native task snapshot, 실제 `SessionEnd`, workspace label, permission/tool lifecycle과 subagent running → stopped 확인 |
77
112
  | 앱 embedded Codex | `0.146.0-alpha.9.2` | isolated plugin install/runtime 및 lifecycle probe |
78
113
  | Homebrew Codex CLI | `0.146.0` | isolated plugin install/runtime probe |
79
114
 
@@ -122,20 +157,18 @@ node bin/codex-agent-view.mjs install
122
157
 
123
158
  `/hooks`는 CLI TUI command이며 `codex /hooks`라는 shell command가 아니다. Hook definition이 바뀌면 hash도 바뀌므로 다시 검토한다. 일반 설치에서 trust-bypass option을 사용하지 않는다.
124
159
 
125
- ### Monitor 실행과 상태 확인
160
+ ### Maintainer·고급 진단 전용 CLI
126
161
 
127
- Monitor를 foreground로 실행한다.
162
+ 이 절은 package 개발자와 문제 보고를 위한 진단 참고 자료이며 일반 사용자 사용법이 아니다. 설치가 끝난 사용자는 Codex 앱에서 snapshot이나 live 화면을 요청해야 한다. 아래 명령과 localhost 주소를 정상 사용 순서에 넣거나 사용자에게 직접 관리하도록 요구하지 않는다.
128
163
 
129
- ```bash
130
- node bin/codex-agent-view.mjs start
131
- ```
132
-
133
- 기본 주소는 `127.0.0.1:43127`이다. `start`는 URL만 출력하며 운영체제의 외부 browser를 자동으로 열지 않는다. 외부 browser 열기는 사용자가 명시적으로 원할 때만 다음처럼 실행한다.
164
+ Source checkout에서 local runtime을 별도로 검증해야 할 때만 다음처럼 실행할 수 있다.
134
165
 
135
166
  ```bash
136
- node bin/codex-agent-view.mjs start --open
167
+ node bin/codex-agent-view.mjs start --no-open
137
168
  ```
138
169
 
170
+ Runtime은 loopback interface에만 bind된다. `--no-open`은 운영체제의 외부 browser를 열지 않는 진단용 형태다. 출력되는 tokenized URL은 비밀로 취급하고 공유하거나 문서·issue에 붙이지 않는다.
171
+
139
172
  다른 terminal에서 상태를 확인한다.
140
173
 
141
174
  ```bash
@@ -154,26 +187,26 @@ Monitor가 꺼져 있어도 hook sender는 fail-open으로 끝나 Codex task를
154
187
 
155
188
  Monitor가 실행 중이고 plugin enable/trust가 끝난 뒤 생성되거나 재개되는 task는 hook이 도착하면 task ID를 미리 등록하지 않아도 자동으로 목록에 나타난다. UI 검색은 이렇게 자동 수신된 목록을 거르는 선택적 filter일 뿐이며, task 추적을 시작하거나 ID를 등록하는 기능이 아니다. Plugin 설치·trust 전이나 monitor downtime에 이미 지나간 event는 재생되지 않는다.
156
189
 
157
- ### npm에서 설치
190
+ ### npm 설치 명령 참고
158
191
 
159
- 아래는 아직 public `latest`인 `0.2.1`의 fallback 설치 방법이다. App-first `0.3.0` candidate는 publish 전이므로 이 명령으로 설치된다고 안내하지 않는다.
192
+ 아래 명령은 이 package version인 exact `0.3.2`를 지정하는 설치 명령이다.
160
193
 
161
194
  ```bash
162
- npm install --global codex-agent-view@0.2.1
195
+ npm install --global codex-agent-view@0.3.2
163
196
  codex-agent-view install
164
- codex-agent-view doctor
165
- codex-agent-view start
166
197
  ```
167
198
 
199
+ 이 두 명령 뒤에는 Codex 앱을 완전히 다시 열고 Plugins 화면에서 설치·활성화를 확인한 다음, 새 task에서 `@codex-agent-view`를 선택한다. Monitor 시작과 상태 조회는 plugin이 앱 안의 요청에 맞춰 처리하므로 사용자가 CLI를 실행하지 않는다.
200
+
168
201
  Global install 없이 exact version을 일회성으로 실행할 수도 있다.
169
202
 
170
203
  ```bash
171
- npx --yes codex-agent-view@0.2.1 doctor
172
- npx --yes codex-agent-view@0.2.1 install
173
- npx --yes codex-agent-view@0.2.1 start
204
+ npx --yes codex-agent-view@0.3.2 install
174
205
  ```
175
206
 
176
- `0.2.0` public artifact는 isolated global install과 exact-version `npx` 양쪽에서 CLI lifecycle을 통과했고 fixture event가 status/UI에 반영됐지만, 이후 실행 중이던 실제 공식 앱 process에서는 event 0건이 재현됐다. 별도의 public exact `0.2.1` artifact는 this-device global install, copied marketplace, clean-cache exact-version `npx --version`, tag/release/source byte comparison을 통과했다. 재시작한 공식 앱 E2E에서도 실제 hook 8종과 task ID 등록 없는 자동 표시를 확인했다. 후속 `0.3.0` source E2E의 browser monitor에서 실제 `SessionEnd`도 관찰했지만 `0.3.0` public artifact evidence는 아직 없다. Registry evidence와 검증 경계는 [docs/distribution.md](docs/distribution.md)에 기록한다.
207
+ `npx` 경로도 explicit `install`을 실행하는 최초 설치 방법일 뿐이다. 이후 사용은 동일하게 Codex 앱 안에서 진행한다.
208
+
209
+ `0.2.0`/`0.2.1`/`0.3.0`/`0.3.1` evidence는 historical record로 보존한다. Registry evidence와 검증 경계는 [docs/distribution.md](docs/distribution.md)에 기록한다.
177
210
 
178
211
  npm install 자체는 Codex 설정을 자동 변경하지 않는다. `install` command는 사용자가 명시적으로 실행하며 hook trust도 사용자 검토로 남긴다. npm publish와 Universal Plugins Directory 제출은 서로 별도 절차다. 자세한 배포 경계는 [docs/distribution.md](docs/distribution.md), directory 제출 상태는 [docs/plugin-submission.md](docs/plugin-submission.md)를 참고한다.
179
212
 
@@ -189,22 +222,25 @@ npm install 자체는 Codex 설정을 자동 변경하지 않는다. `install` c
189
222
 
190
223
  ### 제거와 복구
191
224
 
192
- 가능하면 monitor를 `Ctrl+C`로 먼저 종료한 뒤 실행한다.
225
+ 제거는 최초 설치와 마찬가지로 terminal을 사용하는 명시적 lifecycle 작업이다. Maintainer 진단용 foreground monitor를 따로 실행 중인 경우에만 먼저 `Ctrl+C`로 종료하고 다음을 실행한다.
193
226
 
194
227
  ```bash
195
- node bin/codex-agent-view.mjs doctor --json
196
- node bin/codex-agent-view.mjs uninstall
228
+ codex-agent-view uninstall
197
229
  ```
198
230
 
199
231
  기본 `uninstall`은 plugin 등록, marketplace 등록, copied marketplace bundle을 제거하지만 runtime directory의 나머지 data는 보존한다. 사용자가 `doctor`가 보여준 exact runtime directory까지 제거하길 명시적으로 원할 때만 다음을 사용한다.
200
232
 
201
233
  ```bash
202
- node bin/codex-agent-view.mjs uninstall --purge
234
+ codex-agent-view uninstall --purge
203
235
  ```
204
236
 
237
+ Source checkout을 직접 실행한 경우에만 같은 명령의 `node bin/codex-agent-view.mjs uninstall` 또는 `node bin/codex-agent-view.mjs uninstall --purge` 형식을 사용한다.
238
+
205
239
  별도 `PLUGIN_DATA`, `CODEX_AGENT_VIEW_CAPTURE_DIR`, project working directory에 만든 opt-in diagnostic capture는 runtime directory 밖에 있을 수 있다. 정확한 위치를 검토해 별도로 정리하고 broad Codex/home directory를 삭제하지 않는다.
206
240
 
207
- ### Troubleshooting
241
+ ### Maintainer troubleshooting
242
+
243
+ 이 절의 CLI 확인은 명시적인 문제 조사용이다. 정상 사용자는 Codex 앱 안에서 plugin에게 상태 확인을 요청한다.
208
244
 
209
245
  #### `status`가 runtime file 또는 connection error를 출력함
210
246
 
@@ -212,7 +248,7 @@ node bin/codex-agent-view.mjs uninstall --purge
212
248
  node bin/codex-agent-view.mjs doctor --json
213
249
  ```
214
250
 
215
- Monitor가 실행 중인지, stale runtime file인지, runtime directory가 예상한 위치인지 확인한다. Monitor가 실행되지 않았다면 사용자가 원할 때 `start`로 시작한다. 외부 browser는 `--open`을 명시한 경우에만 열린다.
251
+ Monitor가 실행 중인지, stale runtime file인지, runtime directory가 예상한 위치인지 확인한다. 진단 과정에서 runtime을 직접 시작해야 한다면 외부 browser를 열지 않는 `start --no-open`만 사용한다.
216
252
 
217
253
  #### UI에 task/subagent가 없음
218
254
 
@@ -249,22 +285,57 @@ Codex Agent View is a read-only companion plugin that shows privacy-minimized ac
249
285
 
250
286
  > This is an unofficial community project. It is not an OpenAI product, affiliate, or officially supported project.
251
287
 
288
+ ### Quick start: install once, then stay inside the Codex app
289
+
290
+ This README and package are version `codex-agent-view@0.3.2`.
291
+
292
+ Universal Plugins Directory search installation is not available yet, so use a regular terminal for the **initial installation only**:
293
+
294
+ ```bash
295
+ npm install --global codex-agent-view@0.3.2
296
+ codex-agent-view install
297
+ ```
298
+
299
+ The first command installs the npm package. The second explicitly registers that package as a local Codex plugin. `npm install` alone does not change Codex settings, and the package has no `postinstall` script that silently modifies them.
300
+
301
+ After installation:
302
+
303
+ 1. If the Codex app was open during installation, quit it completely and reopen it.
304
+ 2. In the Codex app's **Plugins** screen, confirm that `Codex Agent View` is installed and enabled.
305
+ 3. If a hook-review screen is shown, inspect `hooks/hooks.json` and the `node "${PLUGIN_ROOT}/scripts/send-hook.mjs"` command, then explicitly trust the current definition. Use interactive Codex CLI `/hooks` only as part of installation when the app version does not expose hook review.
306
+ 4. After enablement and hook review, create a **new task** in the Codex app. Events that occurred before installation are not replayed.
307
+ 5. In the new task, open the `@` menu, select `codex-agent-view`, and ask:
308
+
309
+ > Show the currently active tasks and subagents.
310
+
311
+ 6. For hook-level live detail, ask in that same Codex app task:
312
+
313
+ > Open the Codex Agent View live view inside the app.
314
+
315
+ For a live-view request, the plugin internally reuses a healthy local monitor or starts one when needed, then opens it in the **Codex built-in Browser**. Normal users do not run `start`, `status`, or `doctor`, copy localhost URLs or tokens, or manage an external browser.
316
+
317
+ In short: install once in a terminal; perform snapshot queries, status checks, live-view opening, and all routine use inside the Codex app.
318
+
252
319
  ### Status
253
320
 
254
- The current source is an unpublished `0.3.0` candidate; public npm `latest` remains `0.2.1`. The source includes an app-native snapshot skill that prioritizes the official Codex app's built-in thread tools, plus privacy-minimized hooks, a bounded in-memory reducer, an optional token-authenticated `127.0.0.1` dashboard, and lifecycle CLI commands.
321
+ This package version is `0.3.2`. The package includes an app-native snapshot skill that prioritizes the official Codex app's built-in thread tools, plus privacy-minimized hooks, a bounded in-memory reducer, an optional token-authenticated `127.0.0.1` dashboard, and lifecycle CLI commands.
255
322
 
256
323
  Plugin installation and lifecycle payloads were verified with Homebrew Codex CLI and the Codex executable embedded in the official app. However, a real-use attempt that installed and enabled `0.2.0` in an already-running official app process delivered zero events while two subagents ran. The monitor, registration, enablement, and installed bundle were healthy, while app logs showed no sender invocation. Evidence indicates that the same process retained a pre-install `hooks/list` snapshot; persisted exact-hook trust is not exposed through CLI JSON, so the precise skip boundary remains unconfirmed.
257
324
 
258
325
  `0.2.1` adds `SessionStart`, `SessionEnd`, `UserPromptSubmit`, and `Stop` for parent-task lifecycle visibility and makes `status`, `doctor`, and the empty UI distinguish monitor health from hook delivery. In a real E2E after restarting official Codex app `26.727.40816` (`build 6067`) with plugin `0.2.1` installed and enabled, three parent sessions and three subagents appeared automatically without pre-registering task IDs. Real `SessionStart`, `UserPromptSubmit`, `Stop`, `SubagentStart`, `SubagentStop`, `PreToolUse`, `PostToolUse`, and `PermissionRequest` hooks reached the sender, loopback monitor, and UI. `SessionEnd` is wired but has not yet been observed from the real official app, so compatibility for that event is not claimed.
259
326
 
260
- In the lead's `0.3.0` candidate E2E, the official app's built-in thread tools reported the active `kyurasi-next-supabase` task with workspace basename, title, description, explicit `inProgress` status, latest explicit agent commentary, and `subAgentActivity`. Immediately afterward, the list result changed to explicit `idle` with `hasUnreadTurn: true`. The skill separates this into a `Finished / needs review` display group instead of the running/active group, but does not infer completion or success from `idle + unread`. The separate hook/browser monitor also observed a real `SessionEnd`. This is source-candidate evidence, not a claim that `0.3.0` has been published, tagged, released, or installed from a public artifact.
327
+ In the lead's `0.3.0` E2E, the official app's built-in thread tools reported the active `kyurasi-next-supabase` task with workspace basename, title, description, explicit `inProgress` status, latest explicit agent commentary, and `subAgentActivity`. Immediately afterward, the list result changed to explicit `idle` with `hasUnreadTurn: true`. The skill separates this into a `Finished / needs review` display group instead of the running/active group, but does not infer completion or success from `idle + unread`. The separate hook/browser monitor also observed a real `SessionEnd`.
261
328
 
262
- Maintainer npm 2FA is enabled in `auth-and-writes` mode, and the current public `latest`, `codex-agent-view@0.2.1`, is available from the npm registry. npm publication remains separate from Universal Plugins Directory submission; the plugin is not directory-searchable.
329
+ Maintainer npm 2FA is enabled in `auth-and-writes` mode, and `codex-agent-view@0.3.1` is a verified prior public release. npm publication remains separate from Universal Plugins Directory submission; the plugin is not directory-searchable.
263
330
 
264
331
  Verified `0.2.0` release: npm `gitHead` and the annotated `v0.2.0` tag both resolve to commit `00b62af56698ac875e39c7d1386905c157c3a7e8`; the registry SRI/signature and all 21 package files against the tagged source were verified. [GitHub Release v0.2.0](https://github.com/JunhoYoon95/codex-agent-view/releases/tag/v0.2.0) is public. A separate npm provenance attestation is optional and was not published for this release.
265
332
 
266
333
  Public `0.2.1` patch: registry `latest`, version, `Apache-2.0` license, executable mapping, 21 package files, unpacked size `144644`, npm `gitHead` `8d6a67c9aafa23f801235d747ff018d254378970`, shasum, exact SRI, and registry signature were verified. The annotated `v0.2.1` tag was created at and pushed for that same commit, and [GitHub Release v0.2.1](https://github.com/JunhoYoon95/codex-agent-view/releases/tag/v0.2.1) is public. A clean-cache exact-version `npx --version` passed, and all 21 registry-tarball files are byte-identical to the tagged source. This machine's global install and copied marketplace are also byte-identical to those 21 registry files; CLI `0.2.1`, installed/enabled plugin state, all nine hook declarations, automatic live reception, and a probe subagent's running → stopped/UI completion transition were verified.
267
334
 
335
+ Public `0.3.0`: npm `latest`/version at release time, `gitHead` `988132d0b525ee5e63f13a0d924810dd3f1bd93a`, shasum `08e2e5fa8c1133a1dcc3faae8f354535f9fc07b0`, exact SRI, registry signature, 21 files, and an unpacked size of `158.8 kB` were verified. The annotated `v0.3.0` tag was pushed and [GitHub Release v0.3.0](https://github.com/JunhoYoon95/codex-agent-view/releases/tag/v0.3.0) is public. This machine was globally reinstalled from exact public `0.3.0`; the plugin is installed/enabled with all nine hooks wired. Registry-to-global artifact diff is zero, and the copied marketplace matches aside from one ownership marker. The public install monitor received real hooks, `workspace_label: codex-agent-view`, `PermissionRequest`, tool lifecycle events, and a probe subagent's running → stopped transition with `has_out_of_order_events: false`.
336
+
337
+ Public `0.3.1`: npm version/`latest` at release time `0.3.1`, `gitHead` `c515ea28be201dc24d31e13bf465a38145050b69`, shasum `4405b183012c04e7b0bc265d4eb14bf85291dcd9`, integrity `sha512-8oF5uHqZobgPt75I2ymoq3/tx4Ab1YX/cvMPjaJHjV7zxVC5Dh318isoCdsKNi6emXEbiTIdxOgX7GcclyuP8A==`, and 21 files were verified. The annotated `v0.3.1` tag and [GitHub Release v0.3.1](https://github.com/JunhoYoon95/codex-agent-view/releases/tag/v0.3.1) are public. Exact `0.3.1` was reinstalled on this machine, with plugin `installed: true` and `enabled: true`. Public exact `0.3.1` app-only E2E is not claimed.
338
+
268
339
  ### Boundaries
269
340
 
270
341
  Codex Agent View is a live companion, not a historical audit or session-replay product. Bounded in-memory state and reset-on-restart semantics are intentional: they keep privacy and failure boundaries small. SQLite or persistent history is not a missing requirement. Consider it only as a separate explicit opt-in feature if demonstrated user demand justifies retention, migration, deletion, and privacy costs.
@@ -278,22 +349,24 @@ Codex Agent View is a live companion, not a historical audit or session-replay p
278
349
 
279
350
  A separately launched Codex `0.146` App Server `thread/list` fallback was also tested. It reported both the current root and subagents as `notLoaded`, so it did not share the official app's live running/completed state. That separate process is not the same as the built-in thread tools exposed directly by the current official app; `0.3.0` uses the latter for its primary snapshot.
280
351
 
281
- ### Why npm, a local browser UI, and the Plugins Directory are different
352
+ ### The roles of npm, the Codex app live view, and the Plugins Directory
282
353
 
283
354
  - Asking the plugin `Show active tasks` inside the official Codex app is the primary `0.3.0` UX; it does not require starting a monitor or registering task IDs.
284
- - npm distributes the plugin bundle and optional local executable, hook sender, runtime, and static UI as a fallback path.
285
- - The Codex in-app Browser opens the `127.0.0.1` live monitor only when explicitly requested; it is not an external website or telemetry dashboard.
355
+ - npm is the initial installation path that distributes the plugin bundle, its internal hook sender/runtime, and static UI to the user's machine.
356
+ - The live view opens in the Codex built-in Browser only after an explicit in-app request; it is not an external website or telemetry dashboard.
286
357
  - The Universal Plugins Directory does not replace npm. A public in-app custom UI path requires a public HTTPS MCP server and domain verification, which conflicts with this project's local-only, no-external-server boundary. Only a separate listing/skills submission remains under consideration; do not expect Directory search installation until review and publication actually finish.
287
358
 
288
359
  ### Use in the official Codex app — recommended
289
360
 
290
- 1. Select the Codex Agent View plugin in the Codex app.
361
+ Use this flow in a **new task** after completing installation and enablement in the quick start. It requires neither another terminal nor an external browser.
362
+
363
+ 1. Open the `@` menu and select `codex-agent-view`.
291
364
  2. Ask `Show active tasks`.
292
365
  3. The plugin queries running/active tasks plus tasks with explicit `idle` and `hasUnreadTurn: true`. It places the latter in a separate `Finished / needs review` display group without claiming completion or success.
293
366
  4. It displays only workspace basename, display-only title, explicit status, latest explicit agent commentary, and a small `subAgentActivity` tree.
294
367
  5. Prompts, previews, tool input/output, full workspace paths, and internal thread IDs remain hidden by default.
295
368
 
296
- Ask `Open the live Codex Agent View in the built-in Browser` only when you want hook-level live detail. The plugin reuses a healthy monitor and never exposes its tokenized localhost URL in chat.
369
+ Ask `Open the live Codex Agent View in the built-in Browser` inside the app only when you want hook-level live detail. The plugin internally reuses or starts a healthy monitor and never exposes its tokenized localhost URL in chat.
297
370
 
298
371
  ### Requirements and tested versions
299
372
 
@@ -303,13 +376,13 @@ Ask `Open the live Codex Agent View in the built-in Browser` only when you want
303
376
 
304
377
  | Runtime | Tested version | Scope |
305
378
  | --- | --- | --- |
306
- | Official Codex app | `26.727.40816` (`build 6067`) | `0.3.0` source snapshot confirmed active task/title/description/inProgress/commentary/subAgentActivity; browser monitor observed real `SessionEnd` |
379
+ | Official Codex app | `26.727.40816` (`build 6067`) | Public `0.3.0` confirmed app-native task snapshots, real `SessionEnd`, workspace labeling, permission/tool lifecycle, and subagent running → stopped |
307
380
  | App-embedded Codex | `0.146.0-alpha.9.2` | isolated install/runtime and lifecycle probe |
308
381
  | Homebrew Codex CLI | `0.146.0` | isolated install/runtime probe |
309
382
 
310
383
  These versions are a test matrix, not a minimum-version guarantee.
311
384
 
312
- ### Validate and run from source
385
+ ### Validate from source
313
386
 
314
387
  ```bash
315
388
  git clone https://github.com/JunhoYoon95/codex-agent-view.git
@@ -325,13 +398,17 @@ There are no production dependencies; the runtime uses Node.js built-ins. `insta
325
398
 
326
399
  Review the installed plugin and `hooks/hooks.json`, inspect the `node "${PLUGIN_ROOT}/scripts/send-hook.mjs"` command, and explicitly trust the current hook hash. If the app was open before installation, quit it completely and reopen it. Create the test task only after enablement and trust; earlier events are not replayed.
327
400
 
328
- Start the foreground monitor:
401
+ ### Maintainer and advanced diagnostics CLI
402
+
403
+ This section is reference material for package maintainers and explicit troubleshooting. It is not the normal user workflow. After installation, users should request snapshots and live views inside the Codex app; do not make them manage these commands or localhost URLs.
404
+
405
+ Only when validating the local runtime from a source checkout, a maintainer can start it without opening an operating-system browser:
329
406
 
330
407
  ```bash
331
- node bin/codex-agent-view.mjs start
408
+ node bin/codex-agent-view.mjs start --no-open
332
409
  ```
333
410
 
334
- `start` prints the local URL and does not open an operating-system browser by default. Use `--open` only when you explicitly want an external browser. In another terminal:
411
+ The runtime binds only to the loopback interface. Treat the printed tokenized URL as a secret; never share it or paste it into documentation or an issue. In another diagnostic terminal:
335
412
 
336
413
  ```bash
337
414
  node bin/codex-agent-view.mjs status --json
@@ -346,28 +423,28 @@ Once the monitor is running and plugin enablement/trust is complete, hooks from
346
423
 
347
424
  ### Install from npm
348
425
 
349
- The commands below install the public `0.2.1` fallback. The app-first `0.3.0` candidate is not yet published and must not be presented as available from npm.
426
+ The commands below target this exact package version, `0.3.2`.
350
427
 
351
428
  ```bash
352
- npm install --global codex-agent-view@0.2.1
429
+ npm install --global codex-agent-view@0.3.2
353
430
  codex-agent-view install
354
- codex-agent-view doctor
355
- codex-agent-view start
356
431
  ```
357
432
 
433
+ After these two commands, fully reopen the Codex app, verify installation and enablement in Plugins, create a new task, and select `@codex-agent-view`. The plugin handles monitor startup and status checks in response to in-app requests; users do not run those CLI commands.
434
+
358
435
  Or run the exact version without a global install:
359
436
 
360
437
  ```bash
361
- npx --yes codex-agent-view@0.2.1 doctor
362
- npx --yes codex-agent-view@0.2.1 install
363
- npx --yes codex-agent-view@0.2.1 start
438
+ npx --yes codex-agent-view@0.3.2 install
364
439
  ```
365
440
 
366
- The `0.2.0` public artifact passed isolated global and exact-version `npx` CLI lifecycles and delivered fixture events to status/UI, while a later already-running official-app process reproduced zero delivered events. The separate public exact `0.2.1` artifact passed this-device global/copy verification, clean-cache exact-version `npx --version`, and tag/release/source byte comparison. A restarted official-app E2E confirmed eight real hook types and automatic listing without task-ID registration. A later `0.3.0` source E2E observed real `SessionEnd`, but no `0.3.0` public artifact evidence exists yet. See [Distribution](docs/distribution.md).
441
+ The `npx` form is also an initial explicit-install path only. Routine use remains inside the Codex app afterward.
442
+
443
+ The `0.2.0`, `0.2.1`, `0.3.0`, and `0.3.1` evidence remains as historical release record. See [Distribution](docs/distribution.md).
367
444
 
368
445
  npm installation does not modify Codex settings automatically. The explicit `install` command performs local plugin registration and leaves hook trust to the user. npm publication and Universal Plugins Directory submission are separate. See [Distribution](docs/distribution.md) and [Plugin submission](docs/plugin-submission.md).
369
446
 
370
- ### Troubleshooting an empty monitor
447
+ ### Maintainer troubleshooting for an empty monitor
371
448
 
372
449
  1. Run `codex-agent-view doctor --json` and check plugin `installed`, `enabled`, hook `wiring_ok`, and monitor `ok`.
373
450
  2. If `monitor.events_received` is `false`, do not confuse monitor connectivity with successful hook delivery.
@@ -387,14 +464,19 @@ Read [Privacy](docs/privacy.md), [Security](SECURITY.md), and [Support](SUPPORT.
387
464
 
388
465
  ### Uninstall
389
466
 
390
- Stop the monitor with `Ctrl+C` when practical, then run:
467
+ Uninstall is an explicit terminal lifecycle action, like initial installation. Only when a maintainer foreground monitor is already running, stop that diagnostic process with `Ctrl+C`, then run:
391
468
 
392
469
  ```bash
393
- node bin/codex-agent-view.mjs doctor --json
394
- node bin/codex-agent-view.mjs uninstall
470
+ codex-agent-view uninstall
471
+ ```
472
+
473
+ The default command removes plugin/marketplace registration and the copied bundle while preserving remaining runtime data. Use the following only after reviewing the exact runtime directory and explicitly deciding to remove it:
474
+
475
+ ```bash
476
+ codex-agent-view uninstall --purge
395
477
  ```
396
478
 
397
- The default command removes plugin/marketplace registration and the copied bundle while preserving remaining runtime data. Use `uninstall --purge` only after reviewing the exact runtime directory and explicitly deciding to remove it. Opt-in captures outside that directory require separate, exact cleanup.
479
+ For a source checkout only, use the equivalent `node bin/codex-agent-view.mjs uninstall` or `node bin/codex-agent-view.mjs uninstall --purge` form. Opt-in captures outside that directory require separate, exact cleanup.
398
480
 
399
481
  ### Documentation and license
400
482
 
package/bin/codex-agent-view.mjs CHANGED
@@ -168,12 +168,6 @@ async function start(args) {
168
168
  }
169
169
 
170
170
  const monitor = await startMonitorServer({ port: options.port });
171
- process.stdout.write(`Codex Agent View is running at ${monitor.url}\n`);
172
- process.stdout.write("Press Ctrl+C to stop the in-memory monitor.\n");
173
- if (options.open) {
174
- openBrowser(monitor.url);
175
- }
176
-
177
171
  let stopping = false;
178
172
  const stop = async () => {
179
173
  if (stopping) return;
@@ -183,6 +177,12 @@ async function start(args) {
183
177
  };
184
178
  process.once("SIGINT", stop);
185
179
  process.once("SIGTERM", stop);
180
+
181
+ process.stdout.write(`Codex Agent View is running at ${monitor.url}\n`);
182
+ process.stdout.write("Press Ctrl+C to stop the in-memory monitor.\n");
183
+ if (options.open) {
184
+ openBrowser(monitor.url);
185
+ }
186
186
  }
187
187
 
188
188
  async function fetchState() {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "codex-agent-view",
3
- "version": "0.3.0",
3
+ "version": "0.3.2",
4
4
  "description": "Read-only Codex app task view with an optional local live monitor.",
5
5
  "type": "module",
6
6
  "main": "./src/core/index.mjs",
package/skills/codex-agent-view/SKILL.md CHANGED
@@ -90,6 +90,11 @@ Use the packaged CLI only when the Codex app thread tools are not available in
90
90
  the current surface. Do not switch to the CLI merely because one app task lacks
91
91
  details or the bounded list is empty.
92
92
 
93
+ This fallback is an agent-internal diagnostic path, not a normal user workflow.
94
+ Run every command below through the plugin's available execution capability.
95
+ Never tell the user to open a terminal, type a CLI command, copy a localhost
96
+ URL, or manage the monitor process for ordinary status viewing.
97
+
93
98
  1. Run `codex-agent-view status --json`.
94
99
  2. If it succeeds, summarize its observed sessions, subagent states,
95
100
  permission state, update time, and diagnostics without exposing IDs or
@@ -108,6 +113,10 @@ observation window.
108
113
 
109
114
  Only when the user explicitly asks to open, show, or start the live view:
110
115
 
116
+ The plugin agent performs the health check and any required start internally.
117
+ The user's entire interaction after installation remains inside the official
118
+ Codex app; do not turn the commands below into instructions for the user.
119
+
111
120
  1. Check monitor health with the packaged CLI.
112
121
  2. If it is not running, start it with `codex-agent-view start --no-open` so the
113
122
  CLI never launches the operating system's external browser.