@narumitw/pi-btw 0.54.1 β 0.55.0
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 +109 -109
- package/dist/index.ts +2898 -0
- package/dist/index.ts.map +7 -0
- package/package.json +9 -5
- package/src/fullscreen-ui.ts +33 -8
package/README.md
CHANGED
|
@@ -1,27 +1,19 @@
|
|
|
1
|
-
# π¬ pi-btw β Side Questions
|
|
1
|
+
# π¬ pi-btw β Ask Side Questions Without Derailing the Main Task
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@narumitw/pi-btw) [](https://pi.dev) [](./LICENSE)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Ask temporary questions in a separate side thread while the main Pi conversation and coding task stay focused.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Bring back only the answer or context you explicitly choose.
|
|
8
8
|
|
|
9
9
|
## β¨ Features
|
|
10
10
|
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
- Resumes any non-empty side thread retained by the current Pi session, listed by its first question.
|
|
18
|
-
- Queues Pi-style `Steering` questions while an answer is running and processes them one at a time.
|
|
19
|
-
- Optionally brings the latest answer, a question-to-end suffix, an exact line range, or the entire side thread into the main editor.
|
|
20
|
-
- Uses the current session branch as context.
|
|
21
|
-
- Uses Pi's current model or an independent model selected in `pi-btw.json`.
|
|
22
|
-
- Uses a pi-btw thinking level that can either start from the main thread or use a fixed remembered value.
|
|
23
|
-
- Does not append the side question or answer to the main conversation.
|
|
24
|
-
- Works as an independently installable npm Pi extension package.
|
|
11
|
+
- Starts a fresh side thread immediately with `/btw <question>` or opens the manager with `/btw`.
|
|
12
|
+
- Uses any persisted main-session branch as context without switching that branch.
|
|
13
|
+
- Supports scrollable answers, follow-up questions, queued steering, and resumable in-memory threads.
|
|
14
|
+
- Keeps side questions and answers out of the main conversation by default.
|
|
15
|
+
- Brings back only the latest answer, a selected range, a question suffix, or the complete side thread when requested.
|
|
16
|
+
- Uses Pi's current model and thinking level or independent saved choices.
|
|
25
17
|
|
|
26
18
|
## π¦ Install
|
|
27
19
|
|
|
@@ -35,13 +27,21 @@ Try without installing permanently:
|
|
|
35
27
|
pi -e npm:@narumitw/pi-btw
|
|
36
28
|
```
|
|
37
29
|
|
|
38
|
-
|
|
30
|
+
Build and try this package locally from the repository root:
|
|
39
31
|
|
|
40
32
|
```bash
|
|
33
|
+
npm --workspace @narumitw/pi-btw run build
|
|
41
34
|
pi -e ./packages/pi-btw
|
|
42
35
|
```
|
|
43
36
|
|
|
44
|
-
|
|
37
|
+
The package declares `dist/index.ts`, so an unbuilt local checkout must run the build before Pi loads the package directory.
|
|
38
|
+
|
|
39
|
+
## π Quick start
|
|
40
|
+
|
|
41
|
+
Run `/btw <question>` to start a side thread immediately, or run `/btw` to choose context and settings first.
|
|
42
|
+
Side-thread questions and answers remain separate from the main conversation unless you explicitly bring selected context back.
|
|
43
|
+
|
|
44
|
+
## π¬ Commands
|
|
45
45
|
|
|
46
46
|
Open the pi-btw menu or provide the first question immediately:
|
|
47
47
|
|
|
@@ -73,75 +73,70 @@ Opening and closing a thread without a new result does not reorder it.
|
|
|
73
73
|
`/btw <question>` bypasses this menu and always starts a fresh side thread.
|
|
74
74
|
Its answer opens above the side-thread editor.
|
|
75
75
|
The side thread uses a dedicated full-screen terminal view.
|
|
76
|
-
The main agent continues running in the background, but its screen rendering stays suspended until
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
`
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
`pi-btw.json` for the next invocation by default.
|
|
90
|
-
Settings to keep fixed-level changes local to the current side thread.
|
|
91
|
-
selected, shortcut changes are always local to the current side thread.
|
|
92
|
-
session's thinking level.
|
|
93
|
-
While a response is running, the transcript and composer remain visible above an `Answeringβ¦`
|
|
94
|
-
|
|
95
|
-
Type another question and press `Enter` to queue it as `Steering`; queued questions are shown in
|
|
96
|
-
submission order and answered one at a time after the active response completes.
|
|
76
|
+
The main agent continues running in the background, but its screen rendering stays suspended until `/btw` closes, so new main-thread output cannot move a mouse selection inside the side thread.
|
|
77
|
+
Drag the primary mouse button across side-thread text to request a copy through Pi's host clipboard helper.
|
|
78
|
+
The view reports `Copied!` when Pi accepts the copy and `Copy failed` when Pi reports failure; actual clipboard availability still depends on operating-system and terminal support.
|
|
79
|
+
Returning from `/btw` redraws the main view with everything produced while it was hidden.
|
|
80
|
+
A compact `btw Β· side thread` header stays fixed above the content so the ephemeral workspace remains recognizable while scrolling.
|
|
81
|
+
Messages use Pi's normal user and assistant presentation without numbered turns or role labels.
|
|
82
|
+
Type each question and press `Enter`; no follow-up shortcut is required.
|
|
83
|
+
Press `Ctrl+Shift+F` to search completed or answering transcript content.
|
|
84
|
+
Press `Enter` or `Ctrl+G` for the next match, `Shift+Enter` or `Ctrl+Shift+G` for the previous match, and `Escape` to close search.
|
|
85
|
+
Search uses Pi's active theme, keeps the composer available after closing the search overlay, and does not include fixed header or footer chrome.
|
|
86
|
+
Previous side questions and answers remain available to the model and visible for that invocation.
|
|
87
|
+
The side-thread header shows its current thinking level.
|
|
88
|
+
Press Pi's configured `app.thinking.cycle` shortcut (`Shift+Tab` by default) in the composer to cycle the levels supported by the side-thread model; every later question uses the displayed level until it is changed again.
|
|
89
|
+
When a fixed thinking level is selected, each shortcut change is also written to `pi-btw.json` for the next invocation by default.
|
|
90
|
+
Turn **Remember thinking level changes** off in Settings to keep fixed-level changes local to the current side thread.
|
|
91
|
+
When **Same as main thread** is selected, shortcut changes are always local to the current side thread.
|
|
92
|
+
Neither path changes the main session's thinking level.
|
|
93
|
+
While a response is running, the transcript and composer remain visible above an `Answeringβ¦` status.
|
|
94
|
+
Type another question and press `Enter` to queue it as `Steering`; queued questions are shown in submission order and answered one at a time after the active response completes.
|
|
97
95
|
A queued question uses the side thread's thinking level when its turn begins.
|
|
98
96
|
A failed active response is shown in the transcript and does not discard later steering questions.
|
|
99
97
|
Use the mouse wheel or trackpad to scroll transcript history like Pi's main thread.
|
|
100
|
-
Keyboard `PgUp`/`PgDn` history navigation remains available.
|
|
101
|
-
It appears in the footer only when the transcript can scroll.
|
|
98
|
+
Keyboard `PgUp`/`PgDn` history navigation remains available and appears in the footer only when the transcript can scroll.
|
|
102
99
|
Press `Ctrl+C` to cancel the active response and discard the ephemeral side-thread draft and steering queue.
|
|
103
100
|
Completed questions, answers, and visible errors remain available through Resume until the current extension instance ends.
|
|
104
101
|
Steering remains entirely inside pi-btw and never appends to the main conversation or editor.
|
|
105
102
|
|
|
106
|
-
After at least one successful answer, press `Ctrl+R` to bring selected context to the main
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
`Escape` returns and `Ctrl+C` closes without bringing anything to main.
|
|
103
|
+
After at least one successful answer, press `Ctrl+R` to bring selected context to the main editor.
|
|
104
|
+
The scope menu shows the size of the latest question and answer and the entire side thread before you choose.
|
|
105
|
+
Bring the latest question and answer, everything from a chosen question onward, an exact text range, or the entire side thread.
|
|
106
|
+
Question-suffix, exact-range, and entire-thread choices preview the exact editable context block before the side thread closes.
|
|
107
|
+
Pressing `Escape` returns, while `Ctrl+C` closes without bringing anything to main.
|
|
112
108
|
|
|
113
109
|
The text-range selector supports both fast line selection and editor-style character selection.
|
|
114
|
-
It reports whether anything is selected plus the selected line, message, and approximate token
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
Pi's configured keys control vertical navigation, bringing, and going back (`Up`/`Down`, `Enter`,
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
questions, create:
|
|
110
|
+
It reports whether anything is selected plus the selected line, message, and approximate token counts.
|
|
111
|
+
Press `Space` to select the current raw source line, then use `Up`/`Down` to extend by whole lines; press `Space` again to clear it.
|
|
112
|
+
Alternatively, use the arrow keys to move the cursor and `Shift`+arrow keys to extend a character-level selection.
|
|
113
|
+
Starting a Shift selection replaces any active line selection.
|
|
114
|
+
Selected lines include a visible `β` marker in addition to highlighting.
|
|
115
|
+
Pi's configured keys control vertical navigation, bringing, and going back (`Up`/`Down`, `Enter`, and `Escape` by default), and the selector displays the active keys.
|
|
116
|
+
Selection follows raw source text rather than terminal-wrapped visual rows.
|
|
117
|
+
|
|
118
|
+
Bringing context to main closes the side thread and loads a deterministic, editable context block into Pi's main editor.
|
|
119
|
+
It never sends the draft automatically.
|
|
120
|
+
If the main editor already has a draft, append is the recommended default.
|
|
121
|
+
Replace is labeled as destructive and requires a second confirmation; Cancel returns to the side thread without changing either draft.
|
|
122
|
+
Concurrent editor updates made while these menus are open are preserved.
|
|
123
|
+
A success message reports whether context was loaded, appended, or replaced and its approximate size.
|
|
124
|
+
Without an explicit bring-to-main action, closing `/btw` never adds the side thread to the main conversation.
|
|
125
|
+
Non-empty threads remain only in memory for Resume within the current Pi session.
|
|
126
|
+
`/new`, Pi `/resume`, `/reload`, extension replacement, and process restart discard every retained thread.
|
|
127
|
+
Unsent drafts, steering queues, interrupted answers, and model credentials are never retained.
|
|
128
|
+
|
|
129
|
+
## βοΈ Settings
|
|
130
|
+
|
|
131
|
+
By default, `/btw` uses the current session model.
|
|
132
|
+
To use an independent model for side questions, create:
|
|
138
133
|
|
|
139
134
|
```text
|
|
140
135
|
$PI_CODING_AGENT_DIR/pi-btw.json
|
|
141
136
|
```
|
|
142
137
|
|
|
143
|
-
The normal location is `~/.pi/agent/pi-btw.json`.
|
|
144
|
-
setting; pi-btw does not add any environment variables.
|
|
138
|
+
The normal location is `~/.pi/agent/pi-btw.json`.
|
|
139
|
+
`PI_CODING_AGENT_DIR` is an existing Pi setting; pi-btw does not add any environment variables.
|
|
145
140
|
|
|
146
141
|
```json
|
|
147
142
|
{
|
|
@@ -151,47 +146,49 @@ setting; pi-btw does not add any environment variables.
|
|
|
151
146
|
}
|
|
152
147
|
```
|
|
153
148
|
|
|
154
|
-
The `model` value uses `provider/model-id` format.
|
|
155
|
-
model IDs may contain additional slashes, such as `openrouter/anthropic/claude-sonnet`.
|
|
156
|
-
The configured model must exist in Pi's model registry and have usable credentials.
|
|
157
|
-
cannot be found or authenticated, pi-btw warns and falls back to the current session model.
|
|
158
|
-
If neither model is available, `/btw` reports an error and stops.
|
|
159
|
-
`/btw`; it does not change the main session model.
|
|
160
|
-
|
|
161
|
-
Pi calls its reasoning setting the **thinking level**.
|
|
162
|
-
to start each new side thread from the main thread's current thinking level.
|
|
163
|
-
omitting `thinkingLevel` from `pi-btw.json`.
|
|
164
|
-
|
|
165
|
-
Set `thinkingLevel` only when you want a fixed pi-btw starting level.
|
|
166
|
-
`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
|
|
167
|
-
are clamped to the selected side model's capabilities using Pi's model rules.
|
|
168
|
-
keep their own local thinking level instead of re-syncing with the main thread.
|
|
169
|
-
write, or change the main session's `defaultThinkingLevel`.
|
|
170
|
-
|
|
171
|
-
`rememberThinkingLevelChanges` controls only persistence for fixed thinking levels and defaults to
|
|
172
|
-
|
|
173
|
-
thinking level is selected and remembering is on, the concrete level is written for the next
|
|
174
|
-
|
|
175
|
-
shortcut
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
Separate Pi processes and external editors are outside this in-process ordering boundary. The file
|
|
185
|
-
is read for each `/btw` invocation, so edits apply without `/reload`.
|
|
149
|
+
The `model` value uses `provider/model-id` format.
|
|
150
|
+
Only the first `/` is the separator, so model IDs may contain additional slashes, such as `openrouter/anthropic/claude-sonnet`.
|
|
151
|
+
The configured model must exist in Pi's model registry and have usable credentials.
|
|
152
|
+
If it cannot be found or authenticated, pi-btw warns and falls back to the current session model.
|
|
153
|
+
If neither model is available, `/btw` reports an error and stops.
|
|
154
|
+
This selection affects only `/btw`; it does not change the main session model.
|
|
155
|
+
|
|
156
|
+
Pi calls its reasoning setting the **thinking level**.
|
|
157
|
+
In Settings, choose **Same as main thread** to start each new side thread from the main thread's current thinking level.
|
|
158
|
+
This is stored by omitting `thinkingLevel` from `pi-btw.json`.
|
|
159
|
+
|
|
160
|
+
Set `thinkingLevel` only when you want a fixed pi-btw starting level.
|
|
161
|
+
Accepted fixed values are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
|
|
162
|
+
The initial value and shortcut cycle are clamped to the selected side model's capabilities using Pi's model rules.
|
|
163
|
+
Resumed side threads keep their own local thinking level instead of re-syncing with the main thread.
|
|
164
|
+
Pi-btw does not read, write, or change the main session's `defaultThinkingLevel`.
|
|
165
|
+
|
|
166
|
+
`rememberThinkingLevelChanges` controls only persistence for fixed thinking levels and defaults to `true` when omitted.
|
|
167
|
+
A side-thread shortcut always changes that side thread immediately.
|
|
168
|
+
When a fixed thinking level is selected and remembering is on, the concrete level is written for the next invocation; when off, `pi-btw.json` stays unchanged.
|
|
169
|
+
When **Same as main thread** is selected, shortcut changes stay local even when remembering is on.
|
|
170
|
+
If a shortcut write fails, the local change remains active and pi-btw warns that it was not remembered.
|
|
171
|
+
A failed Settings-screen save instead restores the previous displayed value.
|
|
172
|
+
|
|
173
|
+
A missing settings file is a side-effect-free read: pi-btw creates it only after a Settings change or a remembered shortcut change.
|
|
174
|
+
Saves are ordered within the Pi process and published atomically with a same-directory temporary file and rename.
|
|
175
|
+
They preserve `model` and unknown fields; malformed or invalid files block saves and remain unchanged.
|
|
176
|
+
Settings must be valid UTF-8 and no larger than 64 KiB, so unexpectedly large or invalidly encoded files are rejected without being rewritten.
|
|
177
|
+
Separate Pi processes and external editors are outside this in-process ordering boundary.
|
|
178
|
+
The file is read for each `/btw` invocation, so edits apply without `/reload`.
|
|
186
179
|
|
|
187
180
|
## π§ Why use pi-btw?
|
|
188
181
|
|
|
189
|
-
Normal assistant messages become part of the main Pi conversation and can distract the coding agent from the task.
|
|
182
|
+
Normal assistant messages become part of the main Pi conversation and can distract the coding agent from the task.
|
|
183
|
+
`pi-btw` creates a lightweight side channel for context-aware questions, making it useful for pair programming, debugging, code review, and repository exploration.
|
|
190
184
|
|
|
191
185
|
## ποΈ Package layout
|
|
192
186
|
|
|
193
187
|
```txt
|
|
194
188
|
packages/pi-btw/
|
|
189
|
+
βββ dist/ # Generated TypeScript runtime loaded by Jiti
|
|
190
|
+
βββ scripts/
|
|
191
|
+
β βββ build-runtime.mjs # Deterministic runtime builder and boundary validator
|
|
195
192
|
βββ src/
|
|
196
193
|
β βββ index.ts
|
|
197
194
|
β βββ btw.ts
|
|
@@ -213,15 +210,18 @@ The package exposes its Pi extension through `package.json`:
|
|
|
213
210
|
```json
|
|
214
211
|
{
|
|
215
212
|
"pi": {
|
|
216
|
-
"extensions": ["./
|
|
213
|
+
"extensions": ["./dist/index.ts"]
|
|
217
214
|
}
|
|
218
215
|
}
|
|
219
216
|
```
|
|
220
217
|
|
|
218
|
+
The generated runtime is built from the authoritative `src/index.ts` graph and does not import back into `src`.
|
|
219
|
+
|
|
221
220
|
## π Keywords
|
|
222
221
|
|
|
223
222
|
Pi extension, Pi coding agent, AI coding agent, side question command, agent chat workflow, TypeScript Pi package, npm Pi extension.
|
|
224
223
|
|
|
225
224
|
## π License
|
|
226
225
|
|
|
227
|
-
MIT.
|
|
226
|
+
MIT.
|
|
227
|
+
See [`LICENSE`](./LICENSE).
|