@narumitw/pi-btw 0.55.4 β 0.56.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 +125 -88
- package/dist/index.ts +159 -50
- package/dist/index.ts.map +2 -2
- package/package.json +5 -8
- package/src/btw.ts +31 -26
- package/src/fullscreen-ui.ts +130 -22
- package/src/menu.ts +34 -2
- package/src/settings.ts +16 -0
package/README.md
CHANGED
|
@@ -2,18 +2,17 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@narumitw/pi-btw) [](https://pi.dev) [](./LICENSE)
|
|
4
4
|
|
|
5
|
-
Ask
|
|
6
|
-
|
|
7
|
-
Bring back only the answer or context you explicitly choose.
|
|
5
|
+
Ask questions in a temporary side thread without adding them to the main Pi conversation.
|
|
6
|
+
Only context you explicitly bring back is loaded into the main editor.
|
|
8
7
|
|
|
9
8
|
## β¨ Features
|
|
10
9
|
|
|
11
|
-
- Starts a
|
|
12
|
-
- Uses any persisted main-session branch as context without switching
|
|
13
|
-
- Supports scrollable answers, follow-up questions, queued steering, and
|
|
10
|
+
- Starts a side thread immediately with `/btw <question>` or opens the manager with `/btw`.
|
|
11
|
+
- Uses any persisted main-session branch as context without switching branches.
|
|
12
|
+
- Supports scrollable answers, transcript search, follow-up questions, queued steering, and in-memory resume.
|
|
14
13
|
- Keeps side questions and answers out of the main conversation by default.
|
|
15
|
-
- Brings back
|
|
16
|
-
- Uses Pi's current model and thinking level or
|
|
14
|
+
- Brings back the latest answer, a question suffix, an exact range, or the complete thread only when requested.
|
|
15
|
+
- Uses Pi's current model and thinking level or saved pi-btw choices.
|
|
17
16
|
|
|
18
17
|
## π¦ Install
|
|
19
18
|
|
|
@@ -35,15 +34,17 @@ pi -e ./packages/pi-btw
|
|
|
35
34
|
```
|
|
36
35
|
|
|
37
36
|
The package declares `dist/index.ts`, so an unbuilt local checkout must run the build before Pi loads the package directory.
|
|
37
|
+
Pi extensions run with the Pi process's user permissions, so install only trusted packages.
|
|
38
38
|
|
|
39
39
|
## π Quick start
|
|
40
40
|
|
|
41
|
-
|
|
42
|
-
|
|
41
|
+
In TUI mode, run `/btw <question>` to start immediately or `/btw` to choose context and settings first.
|
|
42
|
+
The side thread stays separate until you explicitly bring context to the main editor.
|
|
43
43
|
|
|
44
44
|
## π¬ Commands
|
|
45
45
|
|
|
46
|
-
|
|
46
|
+
`/btw` is TUI-only.
|
|
47
|
+
Open the manager or provide the first question immediately:
|
|
47
48
|
|
|
48
49
|
```text
|
|
49
50
|
/btw
|
|
@@ -59,72 +60,97 @@ Examples:
|
|
|
59
60
|
/btw is this API name idiomatic?
|
|
60
61
|
```
|
|
61
62
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
The
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
63
|
+
### Choose context or resume a thread
|
|
64
|
+
|
|
65
|
+
Running `/btw` opens a manager with **Start side thread** selected first.
|
|
66
|
+
**Start from main thread treeβ¦** opens Pi's session tree and uses the root-to-selected-entry path, including the selected entry, as context.
|
|
67
|
+
This choice preserves the main editor draft and does not navigate, fork, append to, or switch the main conversation.
|
|
68
|
+
The tree is a snapshot of persisted entries, and the side thread keeps immutable context even if the main conversation later changes.
|
|
69
|
+
Escape returns to the manager, and Ctrl+C closes the flow.
|
|
70
|
+
Native tree copying reports success or failure.
|
|
71
|
+
An explicit `Shift+L` label edit is the only main-session mutation available from this selector and persists through Pi.
|
|
72
|
+
|
|
73
|
+
When non-empty threads exist in memory, **Resume side thread** opens a bounded searchable list.
|
|
74
|
+
Search matches the first question and question count while retaining each raw thread ID.
|
|
75
|
+
Each row uses the first question as its fixed title and shows the question count.
|
|
76
|
+
Rows are ordered by the newest recorded answer or visible error; opening and closing without a new result does not reorder them.
|
|
77
|
+
**Settings** controls the starting thinking level, fixed-level shortcut memory, and automatic selection copying.
|
|
78
|
+
`/btw <question>` bypasses the manager and always starts a new thread.
|
|
79
|
+
|
|
80
|
+
### Use the side-thread workspace
|
|
81
|
+
|
|
82
|
+
The side thread uses a dedicated full-screen terminal view with answers above the editor.
|
|
83
|
+
The main agent can continue running, but main-screen rendering stays suspended until `/btw` closes so new output cannot move a mouse selection.
|
|
84
|
+
Returning to Pi redraws everything produced while the main view was hidden.
|
|
85
|
+
|
|
86
|
+
A fixed `btw Β· side thread` header identifies the workspace while scrolling.
|
|
87
|
+
Messages use Pi's normal user and assistant presentation without turn numbers or role labels.
|
|
88
|
+
Type a question and press Enter for each turn.
|
|
89
|
+
Previous successful questions and answers remain visible and available to the side model.
|
|
90
|
+
|
|
91
|
+
Drag the primary mouse button across transcript text to select it.
|
|
92
|
+
Automatic selection copying is on by default and immediately requests a copy through Pi's host clipboard helper.
|
|
93
|
+
When **Copy selection automatically** is off, the selection stays highlighted and Pi's effective `app.message.copy` binding copies it.
|
|
94
|
+
Manual mode requires Pi's current fullscreen selection APIs.
|
|
95
|
+
If those APIs are unavailable, pi-btw restores the main TUI and asks you to update Pi or re-enable automatic copying.
|
|
96
|
+
The view reports `No selection to copy` when that binding is used without an active selection.
|
|
97
|
+
It reports `Copied!` when Pi accepts a clipboard request and `Copy failed` when Pi rejects it.
|
|
98
|
+
Actual clipboard access still depends on the operating system and terminal.
|
|
99
|
+
Ctrl+C always cancels the side flow, even when `app.message.copy` is also mapped to Ctrl+C.
|
|
100
|
+
|
|
101
|
+
Press `Ctrl+Shift+F` to search completed or in-progress transcript content.
|
|
102
|
+
Press Enter or `Ctrl+G` for the next match, `Shift+Enter` or `Ctrl+Shift+G` for the previous match, and Escape to close search.
|
|
103
|
+
Search uses Pi's active theme, excludes fixed header and footer text, and returns focus to the composer when closed.
|
|
104
|
+
|
|
105
|
+
### Change thinking level or queue steering
|
|
106
|
+
|
|
107
|
+
The header shows the side thread's current thinking level.
|
|
108
|
+
In the composer, use Pi's configured `app.thinking.cycle` shortcut (`Shift+Tab` by default) to cycle levels supported by the side model.
|
|
109
|
+
Later questions use the displayed level until it changes again.
|
|
110
|
+
For a fixed starting level, shortcut changes are saved to `pi-btw.json` by default.
|
|
111
|
+
Turn **Remember thinking level changes** off to keep them local to the thread.
|
|
112
|
+
With **Same as main thread**, shortcut changes are always local.
|
|
113
|
+
Neither setting changes the main session's thinking level.
|
|
114
|
+
|
|
115
|
+
During a response, the transcript and composer remain visible above `Answeringβ¦`.
|
|
116
|
+
Submit another question to queue it as `Steering`.
|
|
117
|
+
Queued questions appear in submission order and run one at a time after the active response.
|
|
118
|
+
Each queued question uses the side thread's thinking level when its turn starts.
|
|
119
|
+
A failed response remains visible and does not discard later queued questions.
|
|
120
|
+
Steering never appends to the main conversation or editor.
|
|
121
|
+
|
|
122
|
+
Use the mouse wheel, trackpad, or `PgUp`/`PgDn` to scroll transcript history.
|
|
123
|
+
The footer shows history keys only when scrolling is available.
|
|
124
|
+
Ctrl+C cancels the active response and discards the current draft and steering queue.
|
|
125
|
+
Completed questions, answers, and visible errors remain available through Resume until the extension instance ends.
|
|
126
|
+
|
|
127
|
+
### Bring context to the main editor
|
|
128
|
+
|
|
129
|
+
After a successful answer, press `Ctrl+R` to choose context for the main editor.
|
|
130
|
+
The scope menu shows the size of the latest question and answer and the full thread.
|
|
131
|
+
Choose the latest question and answer, everything from one question onward, an exact range, or the full thread.
|
|
132
|
+
Question-suffix, exact-range, and full-thread choices preview the editable context block before the side thread closes.
|
|
133
|
+
Escape returns, while Ctrl+C closes without bringing context back.
|
|
134
|
+
|
|
135
|
+
The exact-range selector supports whole-line and editor-style character selection.
|
|
136
|
+
It reports selected line, message, and approximate token counts.
|
|
137
|
+
Press Space to select the current raw source line, use Up or Down to extend by lines, and press Space again to clear.
|
|
138
|
+
Alternatively, move with arrow keys and extend a character selection with Shift plus an arrow key.
|
|
139
|
+
Starting a Shift selection replaces an active line selection.
|
|
140
|
+
Selected lines show a `β` marker as well as highlighting.
|
|
141
|
+
Pi's configured keys control vertical navigation, bringing, and going back, with Up, Down, Enter, and Escape as defaults.
|
|
142
|
+
Selection follows raw source text rather than terminal-wrapped rows.
|
|
143
|
+
|
|
144
|
+
Bringing context closes the side thread and loads a deterministic, editable block into Pi's main editor without sending it.
|
|
145
|
+
If a draft already exists, append is the recommended default.
|
|
146
|
+
Replace is marked destructive and requires a second confirmation.
|
|
147
|
+
Cancel returns to the side thread without changing either draft, and concurrent editor updates are preserved.
|
|
148
|
+
A success message reports whether context was loaded, appended, or replaced and gives its approximate size.
|
|
149
|
+
|
|
150
|
+
Without an explicit bring action, closing `/btw` never changes the main conversation.
|
|
151
|
+
Non-empty threads remain in memory only for Resume during the current extension instance.
|
|
152
|
+
`/new`, Pi `/resume`, `/reload`, extension replacement, and process restart discard retained threads.
|
|
153
|
+
Unsent drafts, steering queues, interrupted answers, and model credentials are not retained.
|
|
128
154
|
|
|
129
155
|
## βοΈ Settings
|
|
130
156
|
|
|
@@ -142,14 +168,15 @@ The normal location is `~/.pi/agent/pi-btw.json`.
|
|
|
142
168
|
{
|
|
143
169
|
"model": "anthropic/claude-sonnet-4-5",
|
|
144
170
|
"thinkingLevel": "low",
|
|
145
|
-
"rememberThinkingLevelChanges": true
|
|
171
|
+
"rememberThinkingLevelChanges": true,
|
|
172
|
+
"fullscreenCopyOnSelect": true
|
|
146
173
|
}
|
|
147
174
|
```
|
|
148
175
|
|
|
149
176
|
The `model` value uses `provider/model-id` format.
|
|
150
177
|
Only the first `/` is the separator, so model IDs may contain additional slashes, such as `openrouter/anthropic/claude-sonnet`.
|
|
151
178
|
The configured model must exist in Pi's model registry and have usable credentials.
|
|
152
|
-
If it
|
|
179
|
+
If it is missing or unauthenticated, pi-btw warns and falls back to the current session model.
|
|
153
180
|
If neither model is available, `/btw` reports an error and stops.
|
|
154
181
|
This selection affects only `/btw`; it does not change the main session model.
|
|
155
182
|
|
|
@@ -170,17 +197,25 @@ When **Same as main thread** is selected, shortcut changes stay local even when
|
|
|
170
197
|
If a shortcut write fails, the local change remains active and pi-btw warns that it was not remembered.
|
|
171
198
|
A failed Settings-screen save instead restores the previous displayed value.
|
|
172
199
|
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
200
|
+
`fullscreenCopyOnSelect` controls only pi-btw's dedicated fullscreen view and defaults to `true` when omitted.
|
|
201
|
+
Turn **Copy selection automatically** off to retain highlighted selections and copy them with Pi's effective `app.message.copy` binding.
|
|
202
|
+
Pi-btw does not inherit Pi core's setting of the same name because Pi's public extension API does not expose its effective value.
|
|
203
|
+
|
|
204
|
+
Reading a missing settings file has no side effects.
|
|
205
|
+
Pi-btw creates it only after a Settings change or a remembered shortcut change.
|
|
206
|
+
Within one Pi process, saves run in order and publish atomically through a same-directory temporary file and rename.
|
|
207
|
+
Saves preserve `model` and unknown fields.
|
|
208
|
+
Malformed or invalid files block saves and remain unchanged.
|
|
209
|
+
Files must be valid UTF-8 and no larger than 64 KiB.
|
|
210
|
+
Separate Pi processes and external editors are outside the in-process ordering boundary.
|
|
211
|
+
The file is read for every `/btw` invocation, so edits apply without `/reload`.
|
|
179
212
|
|
|
180
|
-
##
|
|
213
|
+
## π§ Limitations
|
|
181
214
|
|
|
182
|
-
|
|
183
|
-
|
|
215
|
+
- `/btw` supports TUI mode only.
|
|
216
|
+
- Resume state is memory-only and lasts only for the current extension instance.
|
|
217
|
+
- A side thread retains the latest 40,000 characters of main-conversation context and adds a truncation notice when earlier content is omitted.
|
|
218
|
+
- Clipboard access depends on Pi's host helper, the operating system, and the terminal.
|
|
184
219
|
|
|
185
220
|
## ποΈ Package layout
|
|
186
221
|
|
|
@@ -193,12 +228,14 @@ packages/pi-btw/
|
|
|
193
228
|
β βββ index.ts
|
|
194
229
|
β βββ btw.ts
|
|
195
230
|
β βββ bring-to-main.ts
|
|
231
|
+
β βββ fullscreen-ui.ts
|
|
196
232
|
β βββ main-tree-picker.ts
|
|
197
233
|
β βββ menu.ts
|
|
198
234
|
β βββ settings.ts
|
|
199
235
|
β βββ side-thread.ts
|
|
200
236
|
β βββ text.ts
|
|
201
237
|
β βββ transcript-pager.ts
|
|
238
|
+
βββ test/
|
|
202
239
|
βββ README.md
|
|
203
240
|
βββ LICENSE
|
|
204
241
|
βββ tsconfig.json
|