@plannotator/pi-extension 0.8.3
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 +117 -0
- package/index.ts +668 -0
- package/package.json +36 -0
- package/plannotator.html +3258 -0
- package/review-editor.html +1600 -0
- package/server.ts +301 -0
- package/utils.ts +103 -0
package/README.md
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# Plannotator for Pi
|
|
2
|
+
|
|
3
|
+
Plannotator integration for the [Pi coding agent](https://github.com/mariozechner/pi). Adds file-based plan mode with a visual browser UI for reviewing, annotating, and approving agent plans.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
**From npm** (recommended):
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
pi install npm:@plannotator/pi-extension
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
**From source:**
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
git clone https://github.com/backnotprop/plannotator.git
|
|
17
|
+
pi install ./plannotator/apps/pi-extension
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
**Try without installing:**
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
pi -e npm:@plannotator/pi-extension
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Build from source
|
|
27
|
+
|
|
28
|
+
If installing from a local clone, build the HTML assets first:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
cd plannotator
|
|
32
|
+
bun install
|
|
33
|
+
bun run build:pi
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
This builds the plan review and code review UIs and copies them into `apps/pi-extension/`.
|
|
37
|
+
|
|
38
|
+
## Usage
|
|
39
|
+
|
|
40
|
+
### Plan mode
|
|
41
|
+
|
|
42
|
+
Start Pi in plan mode:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
pi --plan
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Or toggle it during a session with `/plannotator` or `Ctrl+Alt+P`.
|
|
49
|
+
|
|
50
|
+
In plan mode the agent is restricted to read-only tools. It explores your codebase, then writes a plan to `PLAN.md` using markdown checklists:
|
|
51
|
+
|
|
52
|
+
```markdown
|
|
53
|
+
- [ ] Add validation to the login form
|
|
54
|
+
- [ ] Write tests for the new validation logic
|
|
55
|
+
- [ ] Update error messages in the UI
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
When the agent calls `exit_plan_mode`, the Plannotator UI opens in your browser. You can:
|
|
59
|
+
|
|
60
|
+
- **Approve** the plan to begin execution
|
|
61
|
+
- **Deny with annotations** to send structured feedback back to the agent
|
|
62
|
+
- **Approve with notes** to proceed but include implementation guidance
|
|
63
|
+
|
|
64
|
+
The agent iterates on the plan until you approve, then executes with full tool access.
|
|
65
|
+
|
|
66
|
+
### Code review
|
|
67
|
+
|
|
68
|
+
Run `/plannotator-review` to open your current git changes in the code review UI. Annotate specific lines, switch between diff views (uncommitted, staged, last commit, branch), and submit feedback that gets sent to the agent.
|
|
69
|
+
|
|
70
|
+
### Markdown annotation
|
|
71
|
+
|
|
72
|
+
Run `/plannotator-annotate <file.md>` to open any markdown file in the annotation UI. Useful for reviewing documentation or design specs with the agent.
|
|
73
|
+
|
|
74
|
+
### Progress tracking
|
|
75
|
+
|
|
76
|
+
During execution, the agent marks completed steps with `[DONE:n]` markers. Progress is shown in the status line and as a checklist widget in the terminal.
|
|
77
|
+
|
|
78
|
+
## Commands
|
|
79
|
+
|
|
80
|
+
| Command | Description |
|
|
81
|
+
|---------|-------------|
|
|
82
|
+
| `/plannotator` | Toggle plan mode on/off |
|
|
83
|
+
| `/plannotator-status` | Show current phase, plan file, and progress |
|
|
84
|
+
| `/plannotator-review` | Open code review UI for current changes |
|
|
85
|
+
| `/plannotator-annotate <file>` | Open markdown file in annotation UI |
|
|
86
|
+
|
|
87
|
+
## Flags
|
|
88
|
+
|
|
89
|
+
| Flag | Description |
|
|
90
|
+
|------|-------------|
|
|
91
|
+
| `--plan` | Start in plan mode |
|
|
92
|
+
| `--plan-file <path>` | Custom plan file path (default: `PLAN.md`) |
|
|
93
|
+
|
|
94
|
+
## Keyboard shortcuts
|
|
95
|
+
|
|
96
|
+
| Shortcut | Description |
|
|
97
|
+
|----------|-------------|
|
|
98
|
+
| `Ctrl+Alt+P` | Toggle plan mode |
|
|
99
|
+
|
|
100
|
+
## How it works
|
|
101
|
+
|
|
102
|
+
The extension manages a state machine: **idle** → **planning** → **executing** → **idle**.
|
|
103
|
+
|
|
104
|
+
During **planning**:
|
|
105
|
+
- Tools restricted to: `read`, `bash` (read-only commands only), `grep`, `find`, `ls`, `write` (plan file only), `exit_plan_mode`
|
|
106
|
+
- `edit` is disabled, bash is gated to a read-only allowlist, writes only allowed to the plan file
|
|
107
|
+
|
|
108
|
+
During **executing**:
|
|
109
|
+
- Full tool access: `read`, `bash`, `edit`, `write`
|
|
110
|
+
- Progress tracked via `[DONE:n]` markers in agent responses
|
|
111
|
+
- Plan re-read from disk each turn to stay current
|
|
112
|
+
|
|
113
|
+
State persists across session restarts via Pi's `appendEntry` API.
|
|
114
|
+
|
|
115
|
+
## Requirements
|
|
116
|
+
|
|
117
|
+
- [Pi](https://github.com/mariozechner/pi) >= 0.53.0
|