@zephyrdeng/pi-review 0.5.0 → 0.5.1
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.
- package/README.md +2 -0
- package/README.zh-CN.md +3 -1
- package/package.json +1 -1
- package/skills/pi-review/SKILL.md +28 -8
- package/skills/pi-review/references/codex-tools.md +34 -0
package/README.md
CHANGED
|
@@ -154,6 +154,8 @@ pi-review --continue <sessionHandle> --mode challenge --model provider/model --
|
|
|
154
154
|
|
|
155
155
|
Agent hosts like Claude Code, Cursor, and Codex typically buffer a Bash tool's stdout until the command exits, so a multi-minute review can look like a silent wait followed by one large dump — even though `pi-review` streams by default. `--progress-log <path>` sidesteps this: it runs the child in `--mode json` and writes its event log to a file in real time, independent of what the calling tool does with stdout.
|
|
156
156
|
|
|
157
|
+
The bundled **pi-review** agent skill tells parent agents to use `--progress-log` by default on those hosts (Pi `/rv` stays on default streaming). Details: [`skills/pi-review/SKILL.md`](skills/pi-review/SKILL.md) and [`skills/pi-review/references/codex-tools.md`](skills/pi-review/references/codex-tools.md).
|
|
158
|
+
|
|
157
159
|
```bash
|
|
158
160
|
# Start the review in the background, writing structured progress events to a file
|
|
159
161
|
pi-review --progress-log /tmp/pi-review.jsonl -- @src/foo.ts &
|
package/README.zh-CN.md
CHANGED
|
@@ -66,7 +66,9 @@ pi-review models
|
|
|
66
66
|
|
|
67
67
|
跟进审查时，`--continue` 与首次 `/rv` 一样可**选填** `--mode`、`--model`（以及后续 CLI 支持的其它选项由 skill 直接调用 CLI 时传入）。
|
|
68
68
|
|
|
69
|
-
`/rv`
|
|
69
|
+
`/rv` 会向主会话注入**英文任务说明**（**仅 Pi 宿主**：默认流式、**不要**自动加 `--no-stream` / `--progress-log`），由主 Agent 调用 `pi-review` CLI。普通 `/rv @path` 无需额外参数。需要整段缓冲时显式 `/rv --no-stream`。
|
|
70
|
+
|
|
71
|
+
**Claude Code / Codex 等 Agent 宿主**：Bash 工具会缓冲 stdout，不能指望“默认流式”在对话里逐字出现；**pi-review skill 默认建议** `--progress-log <path>` + 后台运行 + tail 日志。详见 `skills/pi-review/SKILL.md`、`skills/pi-review/references/codex-tools.md` 与英文 README。
|
|
70
72
|
|
|
71
73
|
## 输出格式
|
|
72
74
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: pi-review
|
|
3
|
-
description: Use pi-review to delegate isolated code, diff, repository, architecture, or plan reviews to a fresh Pi session and return only the review conclusion. Use when the user asks for Pi review, isolated review, code review, plan review, challenge review, review status/progress, or wants to avoid context pollution.
|
|
3
|
+
description: Use pi-review to delegate isolated code, diff, repository, architecture, or plan reviews to a fresh Pi session and return only the review conclusion. On Claude Code or Codex, default to --progress-log with a background shell run and tail the log (chat tools buffer stdout). Use when the user asks for Pi review, isolated review, code review, plan review, challenge review, review status/progress, or wants to avoid context pollution.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Pi Review
|
|
@@ -23,17 +23,36 @@ node ../../bin/pi-review.js --help
|
|
|
23
23
|
|
|
24
24
|
When resolving this fallback, use the actual directory that contains this `SKILL.md`.
|
|
25
25
|
|
|
26
|
+
## Codex / Claude Code
|
|
27
|
+
|
|
28
|
+
- Map skill mentions of `Bash` to your host shell tool.
|
|
29
|
+
- Read **[references/codex-tools.md](./references/codex-tools.md)** (next to this `SKILL.md`) for Codex/Claude Code defaults: `--progress-log` + background run + tail.
|
|
30
|
+
- Do not use a blocking foreground shell alone for live progress; follow **Default workflow by host** below.
|
|
31
|
+
|
|
32
|
+
## Default workflow by host
|
|
33
|
+
|
|
34
|
+
| Host | How to run `pi-review` |
|
|
35
|
+
|------|-------------------------|
|
|
36
|
+
| **Pi** (`/rv`) | Foreground CLI, **default streaming** only. Do **not** add `--no-stream` or `--progress-log` unless the user explicitly asks. |
|
|
37
|
+
| **Claude Code, Codex, Cursor**, and similar AI agents | **Default: `--progress-log <path>` + background run + tail** (see below). Do **not** rely on foreground Bash stdout for “streaming” — the tool buffers until exit. |
|
|
38
|
+
| Scripts / CI | Foreground is fine; use `--no-stream` only when you must buffer until exit. |
|
|
39
|
+
|
|
26
40
|
## Pi host (`/rv`)
|
|
27
41
|
|
|
28
42
|
- In **Pi interactive** sessions, run `pi-review` with **default streaming only** — do **not** add `--no-stream` or `--progress-log` unless the user explicitly asks.
|
|
29
43
|
- The `/rv` extension injects these rules into the parent agent; ordinary `/rv @path` needs no extra flags.
|
|
30
44
|
|
|
31
|
-
## Streaming vs agent hosts
|
|
45
|
+
## Streaming vs agent hosts (Claude Code / Codex)
|
|
32
46
|
|
|
33
|
-
- `pi-review` **streams** child `pi` stdout/stderr to the process terminal by default (`--no-stream` buffers until exit).
|
|
34
|
-
- **
|
|
35
|
-
-
|
|
36
|
-
-
|
|
47
|
+
- `pi-review` **streams** child `pi` stdout/stderr to the process terminal by default (`--no-stream` buffers until exit). That helps **Pi** and real terminals, not most agent chat UIs.
|
|
48
|
+
- **Claude Code, Cursor, Codex**, and similar hosts **buffer tool stdout** until the bash command exits, so the chat shows the review **all at once** even though the CLI is streaming. That is expected—not a misconfiguration.
|
|
49
|
+
- Default `text` mode also produces **no stdout** during tool-use/thinking (only the final answer), so even a local terminal stays quiet for most of a multi-minute review.
|
|
50
|
+
- **Recommended for Claude Code / Codex (live progress):** always use `--progress-log <path>` unless the user explicitly wants a silent blocking wait:
|
|
51
|
+
1. Pick a writable path (e.g. `/tmp/pi-review-<id>.jsonl`).
|
|
52
|
+
2. Start `pi-review --progress-log <path> ...` in a **background** or **async** shell invocation (not a blocking foreground Bash that you wait on with no updates).
|
|
53
|
+
3. While the child runs, **tail** the log and summarize milestones to the user (filter out `message_update` / `tool_execution_update` unless they asked for token-level detail).
|
|
54
|
+
4. When the process exits, show the Markdown body and ASCII `── pi-review` footer from the command result (or re-read the final output as the skill’s step 4 describes).
|
|
55
|
+
- Fall back to a **local terminal** with default streaming only if the host cannot run background commands or tail a file.
|
|
37
56
|
|
|
38
57
|
## Review status (no slash command)
|
|
39
58
|
|
|
@@ -87,8 +106,9 @@ Do not implement findings from a status check; status is informational only.
|
|
|
87
106
|
- Use `--continue <handle>` only with a **Session** path from a prior ASCII footer or `sessionHandle` in `PI_REVIEW_META_JSON`.
|
|
88
107
|
- Put file references as `@path` after `--`.
|
|
89
108
|
- Do not ask `pi-review` to edit, patch, commit, or implement.
|
|
90
|
-
-
|
|
91
|
-
-
|
|
109
|
+
- **Pi `/rv`:** default streaming; no `--progress-log` unless the user asked.
|
|
110
|
+
- **Claude Code / Codex / Cursor:** **include `--progress-log <path>` by default**; background the CLI and tail the log for user-visible progress. Foreground Bash alone does not stream in chat.
|
|
111
|
+
- Add `--no-stream` only when the caller must buffer until exit (cannot combine with `--progress-log`).
|
|
92
112
|
Completion criterion: the command includes the resolved model/default choice and a concrete review target.
|
|
93
113
|
|
|
94
114
|
4. Return the result:
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Agent host tool notes (Codex / Claude Code)
|
|
2
|
+
|
|
3
|
+
Skills may use Claude Code tool names. On **Codex** or **Claude Code**, map them to your native tools:
|
|
4
|
+
|
|
5
|
+
| Skill references | Typical host equivalent |
|
|
6
|
+
|-----------------|-------------------------|
|
|
7
|
+
| `Bash` (run commands) | Native shell / terminal tool |
|
|
8
|
+
| `Read`, `Write`, `Edit` | Native file tools |
|
|
9
|
+
| `Skill` | Load and follow the skill instructions directly |
|
|
10
|
+
|
|
11
|
+
General Codex subagent and worktree mappings live in the **using-superpowers** skill (`references/codex-tools.md`) when that skill is installed; this file is **pi-review–specific** and ships with the pi-review package.
|
|
12
|
+
|
|
13
|
+
## Long-running `pi-review` (default on Codex / Claude Code)
|
|
14
|
+
|
|
15
|
+
Native shell tools usually **buffer stdout/stderr until the command exits**. A multi-minute `pi-review` run can look like a silent wait, then one large dump—even though the CLI streams by default. Default `text` mode also emits **no stdout** during tool-use/thinking (only the final answer).
|
|
16
|
+
|
|
17
|
+
When the **pi-review** skill applies on Codex, Claude Code, or Cursor:
|
|
18
|
+
|
|
19
|
+
1. **Default:** `pi-review --progress-log <path> ...` (writable file, e.g. `/tmp/pi-review-<id>.jsonl`).
|
|
20
|
+
2. Start that command in a **background** or **async** shell invocation—not a single blocking call with no interim updates.
|
|
21
|
+
3. **Tail** the log while the child runs; summarize milestones to the user (skip `message_update` / `tool_execution_update` unless they want token-level detail).
|
|
22
|
+
4. After exit, show the Markdown review and ASCII `── pi-review` footer (skill step 4).
|
|
23
|
+
|
|
24
|
+
**Pi interactive (`/rv`)** is different: foreground `pi-review`, default streaming only—do **not** auto-add `--progress-log` unless the user asked.
|
|
25
|
+
|
|
26
|
+
See the parent skill: sections *Default workflow by host* and *Streaming vs agent hosts (Claude Code / Codex)*.
|
|
27
|
+
|
|
28
|
+
Example tail (milestone events only):
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
tail -f -n +1 /tmp/pi-review.jsonl | jq -c --unbuffered '
|
|
32
|
+
select(.type != "message_update" and .type != "tool_execution_update")
|
|
33
|
+
'
|
|
34
|
+
```
|