peakypanes 0.0.6 β 0.0.8
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 +28 -304
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Peaky Panes
|
|
2
2
|
|
|
3
3
|
```
|
|
4
4
|
ββββ βββββ βββ β β β β ββββ βββ β β βββββ ββββ
|
|
@@ -6,15 +6,23 @@
|
|
|
6
6
|
β βββββ β β β ββ β β β β β ββ βββββ βββββ
|
|
7
7
|
```
|
|
8
8
|
|
|
9
|
-
**
|
|
9
|
+
**Multi-project orchestration in a single TUI for AI agents and dev environments.**
|
|
10
|
+
|
|
11
|
+
[](https://www.npmjs.com/package/peakypanes)
|
|
12
|
+
[](https://github.com/regenrek/homebrew-tap)
|
|
13
|
+
[](https://deepwiki.com/regenrek/peakypanes)
|
|
14
|
+
[](https://pkg.go.dev/github.com/regenrek/peakypanes/cmd/devwatch)
|
|
15
|
+
|
|
10
16
|
|
|
11
17
|
|
|
12
18
|
|
|
13
19
|
|
|
14
|
-
|
|
20
|
+
Run all your projects and AI agents in one dashboard instead of juggling terminal windows or tabs. Define layouts in YAML, share them with your team via git, and get consistent environments everywhere. Sessions are owned by a **native daemon** so they keep running after the UI exits.
|
|
15
21
|
|
|
16
22
|
## Features
|
|
17
23
|
|
|
24
|
+
- π§ **AI agent orchestration** - Run Codex/Claude/agents side by side with quick replies, slash commands, and broadcast
|
|
25
|
+
- ποΈ **Multi-project dashboard** - See every project/session in one TUI without switching windows
|
|
18
26
|
- π¦ **Built-in layouts** - Works out of the box with sensible defaults
|
|
19
27
|
- 𧩠**Exact grids** - Use `grid: 2x3` for consistent rows/columns
|
|
20
28
|
- π **Project-local config** - Commit `.peakypanes.yml` to git for team sharing
|
|
@@ -57,12 +65,6 @@ Using Go
|
|
|
57
65
|
go install github.com/regenrek/peakypanes/cmd/peakypanes@latest
|
|
58
66
|
```
|
|
59
67
|
|
|
60
|
-
**Hot reload (from repo)**
|
|
61
|
-
|
|
62
|
-
```bash
|
|
63
|
-
scripts/dev-watch -- --layout dev-3
|
|
64
|
-
```
|
|
65
|
-
|
|
66
68
|
### Usage
|
|
67
69
|
|
|
68
70
|
**Start a session (auto-detect layout):**
|
|
@@ -70,12 +72,6 @@ scripts/dev-watch -- --layout dev-3
|
|
|
70
72
|
peakypanes start
|
|
71
73
|
```
|
|
72
74
|
|
|
73
|
-
**Use a specific layout:**
|
|
74
|
-
```bash
|
|
75
|
-
peakypanes start --layout dev-3
|
|
76
|
-
peakypanes start --layout fullstack
|
|
77
|
-
```
|
|
78
|
-
|
|
79
75
|
**Create project-local config (recommended for teams):**
|
|
80
76
|
```bash
|
|
81
77
|
cd your-project
|
|
@@ -84,317 +80,45 @@ peakypanes init --local
|
|
|
84
80
|
git add .peakypanes.yml # Share with team
|
|
85
81
|
```
|
|
86
82
|
|
|
87
|
-
|
|
88
|
-
```bash
|
|
89
|
-
peakypanes daemon
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
## Configuration
|
|
83
|
+
## Documentation
|
|
93
84
|
|
|
94
|
-
|
|
85
|
+
- [Configuration & layouts](docs/configuration.md)
|
|
86
|
+
- [Layout builder guide](docs/layout-builder.md)
|
|
87
|
+
- [Dashboard & keybindings](docs/dashboard.md)
|
|
88
|
+
- [CLI reference](docs/cli.md)
|
|
89
|
+
- [Testing](docs/testing.md)
|
|
90
|
+
- [Daemon & troubleshooting](docs/troubleshooting.md)
|
|
91
|
+
- [Release process](RELEASE-DOCS.md)
|
|
95
92
|
|
|
96
|
-
|
|
93
|
+
## Configuration (quick look)
|
|
97
94
|
|
|
98
|
-
|
|
95
|
+
Project-local config lives in `.peakypanes.yml`, and global config lives in `~/.config/peakypanes/config.yml`.
|
|
96
|
+
See the full schema, built-in layouts, and variable expansion in [docs/configuration.md](docs/configuration.md).
|
|
99
97
|
|
|
100
98
|
```yaml
|
|
101
|
-
# .peakypanes.yml
|
|
102
99
|
session: my-project
|
|
103
100
|
|
|
104
101
|
layout:
|
|
105
102
|
panes:
|
|
106
103
|
- title: editor
|
|
107
104
|
cmd: "${EDITOR:-}"
|
|
108
|
-
size: "60%"
|
|
109
105
|
- title: server
|
|
110
106
|
cmd: "npm run dev"
|
|
111
107
|
split: horizontal
|
|
112
|
-
- title: shell
|
|
113
|
-
cmd: ""
|
|
114
|
-
split: vertical
|
|
115
|
-
- title: docker
|
|
116
|
-
cmd: "docker compose logs -f"
|
|
117
|
-
|
|
118
|
-
# Or use exact grids
|
|
119
|
-
# layout:
|
|
120
|
-
# grid: 2x3
|
|
121
|
-
# commands:
|
|
122
|
-
# - "${SHELL:-bash}"
|
|
123
|
-
# - "codex"
|
|
124
|
-
# - "codex"
|
|
125
|
-
# - "codex"
|
|
126
|
-
# - "codex"
|
|
127
|
-
# - "codex"
|
|
128
|
-
# titles:
|
|
129
|
-
# - shell
|
|
130
|
-
# - codex-1
|
|
131
|
-
# - codex-2
|
|
132
|
-
# - codex-3
|
|
133
|
-
# - codex-4
|
|
134
|
-
# - codex-5
|
|
135
|
-
|
|
136
|
-
# Optional per-project dashboard overrides
|
|
137
|
-
# dashboard:
|
|
138
|
-
# sidebar:
|
|
139
|
-
# hidden: true
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
### Global Config (`~/.config/peakypanes/config.yml`)
|
|
143
|
-
|
|
144
|
-
For personal layouts and multi-project management:
|
|
145
|
-
|
|
146
|
-
```yaml
|
|
147
|
-
# Dashboard UI settings (optional)
|
|
148
|
-
# dashboard:
|
|
149
|
-
# project_roots:
|
|
150
|
-
# - ~/projects
|
|
151
|
-
# - ~/code
|
|
152
|
-
|
|
153
|
-
# Custom layouts
|
|
154
|
-
layouts:
|
|
155
|
-
my-custom:
|
|
156
|
-
panes:
|
|
157
|
-
- title: code
|
|
158
|
-
cmd: nvim
|
|
159
|
-
- title: term
|
|
160
|
-
cmd: ""
|
|
161
|
-
|
|
162
|
-
# Projects for quick switching
|
|
163
|
-
projects:
|
|
164
|
-
- name: webapp
|
|
165
|
-
session: webapp
|
|
166
|
-
path: ~/projects/webapp
|
|
167
|
-
layout: fullstack
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
## Variable Expansion
|
|
171
|
-
|
|
172
|
-
Use variables in your layouts:
|
|
173
|
-
|
|
174
|
-
| Variable | Description |
|
|
175
|
-
|----------|-------------|
|
|
176
|
-
| `${PROJECT_PATH}` | Absolute path to project |
|
|
177
|
-
| `${PROJECT_NAME}` | Directory name |
|
|
178
|
-
| `${EDITOR}` | Your $EDITOR |
|
|
179
|
-
| `${VAR:-default}` | Env var with default |
|
|
180
|
-
|
|
181
|
-
```yaml
|
|
182
|
-
layout:
|
|
183
|
-
vars:
|
|
184
|
-
log_file: "${HOME}/logs/${PROJECT_NAME}.log"
|
|
185
|
-
panes:
|
|
186
|
-
- cmd: "tail -f ${log_file}"
|
|
187
|
-
```
|
|
188
|
-
|
|
189
|
-
## Commands
|
|
190
|
-
|
|
191
|
-
```bash
|
|
192
|
-
peakypanes # Open dashboard (direct)
|
|
193
|
-
peakypanes dashboard # Open dashboard (direct)
|
|
194
|
-
peakypanes open # Start session and open dashboard
|
|
195
|
-
peakypanes start # Same as open
|
|
196
|
-
peakypanes start --layout X # Use specific layout
|
|
197
|
-
peakypanes init # Create global config
|
|
198
|
-
peakypanes init --local # Create .peakypanes.yml
|
|
199
|
-
peakypanes layouts # List available layouts
|
|
200
|
-
peakypanes layouts export X # Export layout YAML
|
|
201
|
-
peakypanes clone user/repo # Clone from GitHub and start session
|
|
202
|
-
peakypanes version # Show version
|
|
203
|
-
```
|
|
204
|
-
|
|
205
|
-
## Troubleshooting: daemon stuck / restart
|
|
206
|
-
|
|
207
|
-
The daemon owns sessions and PTYs. If it becomes unresponsive, the only recovery
|
|
208
|
-
today is a manual restart, which **will terminate all running sessions**.
|
|
209
|
-
|
|
210
|
-
**Manual restart (macOS default path):**
|
|
211
|
-
```bash
|
|
212
|
-
kill "$(cat "$HOME/Library/Application Support/peakypanes/daemon.pid")"
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
**Manual restart (Linux default path):**
|
|
216
|
-
```bash
|
|
217
|
-
kill "$(cat "$HOME/.config/peakypanes/daemon.pid")"
|
|
218
|
-
```
|
|
219
|
-
|
|
220
|
-
You can also set `PEAKYPANES_DAEMON_PID` to control the pid file location.
|
|
221
|
-
|
|
222
|
-
### Proposed UX (future)
|
|
223
|
-
If the app detects a hung daemon, it should show a dialog like:
|
|
224
|
-
**βRestart daemon? This will stop all running sessions and close their PTYs.β**
|
|
225
|
-
This makes the data-loss tradeoff explicit before taking action.
|
|
226
|
-
|
|
227
|
-
## Built-in Layouts
|
|
228
|
-
|
|
229
|
-
Core (general) layouts:
|
|
230
|
-
- `auto` (default): no layout flag; auto-detects `.peakypanes.yml` or falls back to `dev-3`
|
|
231
|
-
- `simple`: single pane
|
|
232
|
-
- `split-v`: two vertical panes (left/right)
|
|
233
|
-
- `split-h`: two horizontal panes (top/bottom)
|
|
234
|
-
- `2x2`: 4βpane grid
|
|
235
|
-
- `3x4`: 12βpane grid
|
|
236
|
-
- `codex-dev`: 2x3 grid (shell + 5 codex)
|
|
237
|
-
|
|
238
|
-
Additional built-ins (specialized):
|
|
239
|
-
- `dev-2`: editor + shell
|
|
240
|
-
- `dev-3`: editor + server + shell (default fallback)
|
|
241
|
-
- `fullstack`: editor + server + shell + logs
|
|
242
|
-
- `go-dev`: code/run/test + git
|
|
243
|
-
- `codex-grid`: 2x4 grid running codex in every pane
|
|
244
|
-
|
|
245
|
-
```bash
|
|
246
|
-
# List all layouts
|
|
247
|
-
peakypanes layouts
|
|
248
|
-
|
|
249
|
-
# Export a layout to customize
|
|
250
|
-
peakypanes layouts export codex-dev > .peakypanes.yml
|
|
251
|
-
```
|
|
252
|
-
|
|
253
|
-
## Dashboard UI
|
|
254
|
-
|
|
255
|
-
Running `peakypanes` with no subcommand opens the dashboard UI in the current terminal.
|
|
256
|
-
|
|
257
|
-
The dashboard shows:
|
|
258
|
-
- Projects on top (tabs)
|
|
259
|
-
- Sessions on the left (with pane counts and expandable panes)
|
|
260
|
-
- Live pane preview on the right (native panes are fully interactive)
|
|
261
|
-
- Quick reply bar (always visible) and target pane highlight for follow-ups
|
|
262
|
-
|
|
263
|
-
Navigation (always visible):
|
|
264
|
-
- `ctrl+a/ctrl+d` project, `ctrl+w/ctrl+s` session/panes, `alt+w/alt+s` session only, `tab/β§tab` pane, `ctrl+g` help
|
|
265
|
-
|
|
266
|
-
Key bindings (also shown in the help view):
|
|
267
|
-
Keymap overrides are available in the global config (`~/.config/peakypanes/config.yml`).
|
|
268
|
-
|
|
269
|
-
Project
|
|
270
|
-
- `ctrl+o` open project picker (creates session detached; stay in dashboard)
|
|
271
|
-
- `ctrl+b` toggle sidebar (show/hide sessions list)
|
|
272
|
-
- `alt+c` close project (hides from tabs; sessions keep running; press k in the dialog to kill)
|
|
273
|
-
|
|
274
|
-
Session
|
|
275
|
-
- `enter` attach/start session (when reply is empty)
|
|
276
|
-
- `ctrl+n` new session (pick layout)
|
|
277
|
-
- `ctrl+x` kill session
|
|
278
|
-
- rename session via command palette (`ctrl+p`)
|
|
279
|
-
|
|
280
|
-
Window
|
|
281
|
-
Pane list
|
|
282
|
-
- `ctrl+u` toggle pane list
|
|
283
|
-
|
|
284
|
-
Pane
|
|
285
|
-
- rename pane via command palette (`ctrl+p`)
|
|
286
|
-
- `ctrl+y` peek selected pane in new terminal
|
|
287
|
-
- `ctrl+\` toggle terminal focus (native only; configurable via `dashboard.keymap.terminal_focus`)
|
|
288
|
-
- mouse: single-click selects a pane; double-click toggles terminal focus (native only); `esc` exits focus
|
|
289
|
-
- `f7` scrollback mode (native only; configurable via `dashboard.keymap.scrollback`)
|
|
290
|
-
- `f8` copy mode (native only; configurable via `dashboard.keymap.copy_mode`)
|
|
291
|
-
|
|
292
|
-
Other
|
|
293
|
-
- `ctrl+p` command palette
|
|
294
|
-
- `ctrl+r` refresh, `ctrl+e` edit config, `ctrl+f` filter, `ctrl+c` quit
|
|
295
|
-
|
|
296
|
-
Quick reply details: the input is always activeβtype and press `enter` to send to the highlighted pane. Use `esc` to clear. Toggle terminal focus to send raw keystrokes into the pane. Use scrollback (`f7`) to navigate output and copy mode (`f8`) to select/yank (`v` select, `y` yank, `esc/q` exit).
|
|
297
|
-
|
|
298
|
-
### Dashboard Config (optional)
|
|
299
|
-
|
|
300
|
-
```yaml
|
|
301
|
-
dashboard:
|
|
302
|
-
refresh_ms: 2000
|
|
303
|
-
preview_lines: 12
|
|
304
|
-
preview_compact: true
|
|
305
|
-
idle_seconds: 20
|
|
306
|
-
preview_mode: grid # grid | layout
|
|
307
|
-
sidebar:
|
|
308
|
-
hidden: false
|
|
309
|
-
attach_behavior: current # current | detached
|
|
310
|
-
keymap:
|
|
311
|
-
project_left: ["ctrl+a"]
|
|
312
|
-
project_right: ["ctrl+d"]
|
|
313
|
-
session_up: ["ctrl+w"]
|
|
314
|
-
session_down: ["ctrl+s"]
|
|
315
|
-
session_only_up: ["alt+w"]
|
|
316
|
-
session_only_down: ["alt+s"]
|
|
317
|
-
pane_next: ["tab"]
|
|
318
|
-
pane_prev: ["shift+tab"]
|
|
319
|
-
terminal_focus: ["ctrl+\\"]
|
|
320
|
-
scrollback: ["f7"]
|
|
321
|
-
copy_mode: ["f8"]
|
|
322
|
-
toggle_panes: ["ctrl+u"]
|
|
323
|
-
toggle_sidebar: ["ctrl+b"]
|
|
324
|
-
close_project: ["alt+c"]
|
|
325
|
-
command_palette: ["ctrl+p"]
|
|
326
|
-
help: ["ctrl+g"]
|
|
327
|
-
quit: ["ctrl+c"]
|
|
328
|
-
status_regex:
|
|
329
|
-
success: "(?i)done|finished|success|completed|β
"
|
|
330
|
-
error: "(?i)error|failed|panic|β"
|
|
331
|
-
running: "(?i)running|in progress|building|installing|βΆ"
|
|
332
|
-
agent_detection:
|
|
333
|
-
codex: true
|
|
334
|
-
claude: true
|
|
335
108
|
```
|
|
336
109
|
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
### Agent Status Detection (Codex & Claude Code)
|
|
340
|
-
|
|
341
|
-
PeakyPanes can read per-pane JSON state files to show accurate running/idle/done status for Codex CLI and Claude Code TUI sessions. This is **on by default** and falls back to regex/idle detection if no state file is present. You can disable it via `dashboard.agent_detection`.
|
|
110
|
+
## Dashboard
|
|
342
111
|
|
|
343
|
-
|
|
112
|
+
The dashboard shows projects, sessions, live previews, and a quick-reply bar for slash commands and broadcasts.
|
|
113
|
+
See [docs/dashboard.md](docs/dashboard.md) for keybindings, slash command behavior, and dashboard configuration.
|
|
344
114
|
|
|
345
|
-
|
|
115
|
+
## CLI
|
|
346
116
|
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
```toml
|
|
350
|
-
# ~/.codex/config.toml
|
|
351
|
-
notify = ["python3", "/absolute/path/to/peakypanes/scripts/agent-state/codex-notify.py"]
|
|
352
|
-
```
|
|
353
|
-
|
|
354
|
-
Tip: with `npm i -g peakypanes`, the scripts live under `$(npm root -g)/peakypanes/scripts/agent-state/`.
|
|
355
|
-
Note: Codex `notify` only fires on turn completion, so running state still relies on regex/idle detection between turns.
|
|
356
|
-
|
|
357
|
-
**Claude Code (TUI)**
|
|
358
|
-
|
|
359
|
-
Configure hooks to run the PeakyPanes hook script (Claude passes JSON on stdin). Recommended events:
|
|
360
|
-
`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `Stop`, `SessionEnd`.
|
|
361
|
-
|
|
362
|
-
Example hook command (wire it to each event above in Claude Code):
|
|
363
|
-
|
|
364
|
-
```bash
|
|
365
|
-
python3 /absolute/path/to/peakypanes/scripts/agent-state/claude-hook.py
|
|
366
|
-
```
|
|
367
|
-
|
|
368
|
-
## How Layout Detection Works
|
|
369
|
-
|
|
370
|
-
1. `--layout` flag (highest priority)
|
|
371
|
-
2. `.peakypanes.yml` in current directory
|
|
372
|
-
3. Project entry in `~/.config/peakypanes/config.yml`
|
|
373
|
-
4. Built-in `dev-3` layout (fallback)
|
|
117
|
+
See [docs/cli.md](docs/cli.md) for the full command list and examples.
|
|
374
118
|
|
|
375
119
|
## Testing
|
|
376
120
|
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
```bash
|
|
380
|
-
go test ./... -coverprofile /tmp/peakypanes.cover
|
|
381
|
-
go tool cover -func /tmp/peakypanes.cover | tail -n 1
|
|
382
|
-
```
|
|
383
|
-
|
|
384
|
-
Race tests:
|
|
385
|
-
|
|
386
|
-
```bash
|
|
387
|
-
go test ./... -race
|
|
388
|
-
```
|
|
389
|
-
|
|
390
|
-
Manual npm smoke run (fresh HOME/XDG config):
|
|
391
|
-
|
|
392
|
-
```bash
|
|
393
|
-
scripts/fresh-run
|
|
394
|
-
scripts/fresh-run 0.0.6 --with-project
|
|
395
|
-
```
|
|
396
|
-
|
|
397
|
-
GitHub Actions runs gofmt checks, go vet, go test with coverage, and race on Linux.
|
|
121
|
+
See [docs/testing.md](docs/testing.md) for the full test matrix and CI notes.
|
|
398
122
|
|
|
399
123
|
## Release
|
|
400
124
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "peakypanes",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.8",
|
|
4
4
|
"description": "Tmux layout manager with YAML based configuration.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"homepage": "https://github.com/regenrek/peakypanes",
|
|
@@ -12,10 +12,10 @@
|
|
|
12
12
|
"peakypanes": "bin/peakypanes.js"
|
|
13
13
|
},
|
|
14
14
|
"optionalDependencies": {
|
|
15
|
-
"peakypanes-darwin-x64": "0.0.
|
|
16
|
-
"peakypanes-darwin-arm64": "0.0.
|
|
17
|
-
"peakypanes-linux-x64": "0.0.
|
|
18
|
-
"peakypanes-linux-arm64": "0.0.
|
|
15
|
+
"peakypanes-darwin-x64": "0.0.8",
|
|
16
|
+
"peakypanes-darwin-arm64": "0.0.8",
|
|
17
|
+
"peakypanes-linux-x64": "0.0.8",
|
|
18
|
+
"peakypanes-linux-arm64": "0.0.8"
|
|
19
19
|
},
|
|
20
20
|
"engines": {
|
|
21
21
|
"node": ">=18"
|