pi-side-chat 0.1.0 → 0.1.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 (2) hide show
  1. package/README.md +42 -92
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -4,101 +4,67 @@
4
4
 
5
5
  # pi-side-chat
6
6
 
7
- A Pi extension that forks the current conversation into a temporary side chat while the main agent keeps working.
7
+ **Fork the current conversation into a side chat while the main agent keeps working.**
8
8
 
9
- ```typescript
10
- /side
11
- ```
12
-
13
- Open the overlay, ask a quick question, close it, and go back to what the main agent was already doing.
14
-
15
- ## Why
16
-
17
- This exists for the annoying in-between moments. You're in the middle of a longer task and want to ask something small without derailing the main thread: check an API detail, sanity-check an approach, inspect recent progress, or make a tiny edit off to the side.
18
-
19
- Without a side chat, you either interrupt the main agent, open a completely separate Pi session with no context, or context-switch out to the browser. None of those feel great.
20
-
21
- `pi-side-chat` gives you a fork of the current conversation in an overlay. It starts with the same context, stays separate from the main thread, and disappears when you're done.
22
-
23
- ## Install
9
+ [![npm version](https://img.shields.io/npm/v/pi-side-chat?style=for-the-badge)](https://www.npmjs.com/package/pi-side-chat)
10
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE)
24
11
 
25
- The extension lives in `/Users/nicobailon/.pi/agent/extensions/pi-side-chat`.
12
+ ```bash
13
+ pi install npm:pi-side-chat
14
+ ```
26
15
 
27
- Restart Pi and it will be auto-discovered.
16
+ You're in the middle of a longer task and want to ask something small without derailing the main thread — check an API detail, sanity-check an approach, search something, or peek at what the main agent is doing. Open the overlay, ask, close it. Main thread never gets interrupted.
28
17
 
29
18
  ## Quick Start
30
19
 
31
- Open side chat with `Alt+/` or `/side`.
32
-
33
- Ask a question and press `Enter`.
34
-
35
- Press `Esc` to close it.
36
-
37
- **Toggle focus**: Press `Alt+/` again to switch back to the main editor without closing the overlay. The side chat stays visible but unfocused. Press `Alt+/` once more to refocus it.
38
-
39
- **Toggle mode**: Press `Ctrl+T` to switch from read-only mode to edit mode if you need write access.
40
-
41
- ## What it does
20
+ Open side chat with `Alt+/` or `/side`. Ask a question and press `Enter`.
42
21
 
43
- ### Forks the current conversation
22
+ Press `Esc` to close it. Reopen with `Alt+/` to continue where you left off.
44
23
 
45
- The overlay starts with a copy of the current branch context, so the side agent already knows what you've been working on. It does not write anything back into the main conversation history.
24
+ **Toggle focus** — `Alt+/` switches between the side chat and main editor without closing the overlay.
46
25
 
47
- ### Starts in read-only mode
26
+ **Toggle mode** — `Ctrl+T` switches between read-only and edit mode.
48
27
 
49
- The safe default is read-only. That makes it useful for quick questions, code reading, and checking progress without risking accidental edits.
28
+ **Start fresh** — `Alt+R` re-forks from the latest main context. `Alt+N` starts a blank conversation.
50
29
 
51
- Press `Ctrl+T` to switch between:
52
- - **read-only mode** — safe for quick questions and code reading
53
- - **edit mode** — enables write, edit, and bash tools
30
+ ## Features
54
31
 
55
- The header shows the current mode (`[Read-only]` or `[Edit]`), and the footer shows what `Ctrl+T` will do next.
32
+ **Forks the conversation** — Starts with a copy of the current branch context. All extension tools (web_search, fetch_content, etc.) are available. Does not write back to the main conversation history.
56
33
 
57
- ### Warns on file overlap
34
+ **Persists across close/reopen** — Closing preserves the conversation. Reopening restores it. Use `Alt+R` or `Alt+N` to explicitly start fresh.
58
35
 
59
- If the side chat tries to modify a file that the main agent has already touched, it asks before proceeding.
36
+ **Read-only by default** — Safe for quick questions and code reading. Toggle to edit mode when you need write access.
60
37
 
61
- ```text
62
- File Overlap
63
-
64
- Main agent has modified:
65
- src/api/handler.ts
66
-
67
- Editing may cause conflicts. Proceed?
68
- ```
38
+ | Mode | Tools |
39
+ |------|-------|
40
+ | Read-only | read, grep, find, ls |
41
+ | Edit | read, bash, edit, write (with overlap warnings) |
69
42
 
70
- It does not block automatically. It just makes the conflict explicit.
43
+ **File overlap warnings** — If the side chat tries to modify a file the main agent has touched, it asks before proceeding.
71
44
 
72
- ### Can peek at the main agent
73
-
74
- The side agent gets a `peek_main` tool for reading recent activity from the main session.
75
-
76
- Useful prompts:
45
+ **Peek at the main agent** — The `peek_main` tool reads recent activity from the main session.
77
46
 
78
47
  ```text
79
48
  What is the main agent doing right now?
80
49
  What changed since I opened this side chat?
81
- Show me the last 10 things main did.
82
50
  ```
83
51
 
84
- ### Stays out of the way
85
-
86
- The overlay is non-capturing, so you can leave it visible and switch focus back to the main editor.
87
-
88
- It opens near the top of the screen so the main editor stays visible underneath.
52
+ **Non-capturing overlay** — Leave it visible and switch focus back to the main editor. Opens at the top of the screen so the main editor stays visible underneath.
89
53
 
90
54
  ## Controls
91
55
 
92
56
  | Key | Action |
93
57
  |-----|--------|
94
- | `Alt+/` | Open side chat. When already open, toggles focus between side chat and main editor. |
58
+ | `Alt+/` | Open side chat / toggle focus |
95
59
  | `Enter` | Send message |
96
- | `Esc` | Close side chat |
97
- | `Ctrl+T` | Toggle between read-only mode and edit mode (enables write/edit/bash) |
60
+ | `Esc` | Interrupt streaming, or close when idle |
61
+ | `Alt+R` | Re-fork from latest main context |
62
+ | `Alt+N` | Start empty conversation |
63
+ | `Ctrl+T` | Toggle read-only / edit mode |
98
64
  | `PgUp` / `Shift+↑` | Scroll up |
99
65
  | `PgDn` / `Shift+↓` | Scroll down |
100
66
 
101
- ## Command reference
67
+ ## Command Reference
102
68
 
103
69
  ### `/side`
104
70
 
@@ -108,16 +74,14 @@ Opens the side chat overlay.
108
74
 
109
75
  Available to the side agent only.
110
76
 
111
- Parameters:
112
-
113
77
  | Param | Type | Description |
114
- |------|------|-------------|
115
- | `lines` | integer | Max number of recent items to inspect, default `20`, max `50` |
116
- | `since_fork` | boolean | If `true`, only show activity after the side chat was opened |
78
+ |-------|------|-------------|
79
+ | `lines` | integer | Max items to inspect (default: 20, max: 50) |
80
+ | `since_fork` | boolean | Only show activity after the side chat was opened |
117
81
 
118
82
  ## Configuration
119
83
 
120
- Create `/Users/nicobailon/.pi/agent/extensions/pi-side-chat/config.json` if you want a different shortcut.
84
+ Create a `config.json` next to the extension to change the shortcut:
121
85
 
122
86
  ```json
123
87
  {
@@ -125,32 +89,18 @@ Create `/Users/nicobailon/.pi/agent/extensions/pi-side-chat/config.json` if you
125
89
  }
126
90
  ```
127
91
 
128
- ## How it works
129
-
130
- When you open side chat, the extension clones the current session context, creates a separate agent instance, and renders it in a TUI overlay. The main agent keeps running on its own branch.
92
+ ## How It Works
131
93
 
132
- The extension also listens for main-agent tool execution events and keeps a small in-memory set of paths that have been written. When side chat is in edit mode, its write-capable tools are wrapped so they can warn before touching one of those paths.
94
+ The extension clones the current session context, creates a separate agent instance with all extension-registered tools, and renders it in a TUI overlay. Closing saves the conversation in memory so reopening restores it.
133
95
 
134
- `peek_main` reads the current session branch on demand, formats the recent messages, and returns a compact summary back to the side agent.
96
+ Main-agent tool execution events are tracked to maintain a set of written file paths. In edit mode, write-capable tools are wrapped to warn before touching those paths.
135
97
 
136
- ## File layout
137
-
138
- ```text
139
- pi-side-chat/
140
- ├── index.ts
141
- ├── side-chat-overlay.ts
142
- ├── side-chat-messages.ts
143
- ├── file-activity-tracker.ts
144
- ├── tool-wrapper.ts
145
- ├── banner.png
146
- └── README.md
147
- ```
98
+ `peek_main` reads the current session branch on demand and returns a compact summary.
148
99
 
149
100
  ## Limitations
150
101
 
151
- - Only one side chat can be open at a time.
152
- - Side chat will not open on top of another visible overlay.
153
- - The conversation is ephemeral. Closing the overlay discards it.
154
- - Side chat does not merge messages back into the main thread.
155
- - Bash overlap detection is heuristic. It catches common write cases, not every possible shell write.
156
- - `peek_main` is on-demand, not a live streaming view.
102
+ - One side chat at a time
103
+ - Won't open on top of another visible overlay
104
+ - Does not merge messages back into the main thread
105
+ - Bash overlap detection is heuristic — catches common write patterns, not all
106
+ - `peek_main` is on-demand, not live
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-side-chat",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Pi extension that forks the current conversation into a temporary side chat",
5
5
  "type": "module",
6
6
  "main": "index.js",