panopticon-cli 0.4.5 → 0.4.6
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 +84 -2695
- package/dist/{agents-B5NRTVHK.js → agents-54LDKMHR.js} +8 -3
- package/dist/chunk-44EOY2ZL.js +58 -0
- package/dist/chunk-44EOY2ZL.js.map +1 -0
- package/dist/chunk-BWGFN44T.js +224 -0
- package/dist/chunk-BWGFN44T.js.map +1 -0
- package/dist/chunk-F7NQZD6H.js +49 -0
- package/dist/chunk-F7NQZD6H.js.map +1 -0
- package/dist/chunk-HCTJFIJJ.js +159 -0
- package/dist/chunk-HCTJFIJJ.js.map +1 -0
- package/dist/chunk-JM6V62LT.js +650 -0
- package/dist/chunk-JM6V62LT.js.map +1 -0
- package/dist/chunk-K45YD6A3.js +254 -0
- package/dist/chunk-K45YD6A3.js.map +1 -0
- package/dist/chunk-KGPRXDMX.js +137 -0
- package/dist/chunk-KGPRXDMX.js.map +1 -0
- package/dist/chunk-KQAEUOML.js +278 -0
- package/dist/chunk-KQAEUOML.js.map +1 -0
- package/dist/chunk-NYVQC3D7.js +90 -0
- package/dist/chunk-NYVQC3D7.js.map +1 -0
- package/dist/chunk-PUR532O7.js +1556 -0
- package/dist/chunk-PUR532O7.js.map +1 -0
- package/dist/chunk-VTDDVLCK.js +1977 -0
- package/dist/chunk-VTDDVLCK.js.map +1 -0
- package/dist/chunk-Z24TY3XN.js +916 -0
- package/dist/chunk-Z24TY3XN.js.map +1 -0
- package/dist/chunk-ZHC57RCV.js +44 -0
- package/dist/chunk-ZHC57RCV.js.map +1 -0
- package/dist/{chunk-ITI4IC5A.js → chunk-ZZ3477GY.js} +69 -100
- package/dist/chunk-ZZ3477GY.js.map +1 -0
- package/dist/cli/index.js +4664 -2912
- package/dist/cli/index.js.map +1 -1
- package/dist/dashboard/public/assets/index-CRqsEkmn.css +32 -0
- package/dist/dashboard/public/assets/index-DPSUbu4A.js +645 -0
- package/dist/dashboard/public/index.html +15 -3
- package/dist/dashboard/server.js +45663 -17860
- package/dist/dns-L3L2BB27.js +30 -0
- package/dist/dns-L3L2BB27.js.map +1 -0
- package/dist/index.d.ts +63 -3
- package/dist/index.js +42 -18
- package/dist/index.js.map +1 -1
- package/dist/projects-ESIB34QQ.js +43 -0
- package/dist/projects-ESIB34QQ.js.map +1 -0
- package/dist/remote-agents-Z3R2A5BN.js +25 -0
- package/dist/remote-agents-Z3R2A5BN.js.map +1 -0
- package/dist/remote-workspace-HI4VML6H.js +179 -0
- package/dist/remote-workspace-HI4VML6H.js.map +1 -0
- package/dist/specialist-context-SNCJ7O7G.js +256 -0
- package/dist/specialist-context-SNCJ7O7G.js.map +1 -0
- package/dist/specialist-logs-A7ODEK2T.js +43 -0
- package/dist/specialist-logs-A7ODEK2T.js.map +1 -0
- package/dist/specialists-C7XLNSXQ.js +121 -0
- package/dist/specialists-C7XLNSXQ.js.map +1 -0
- package/dist/traefik-WI3KSRGG.js +12 -0
- package/dist/traefik-WI3KSRGG.js.map +1 -0
- package/package.json +1 -1
- package/templates/traefik/docker-compose.yml +1 -1
- package/templates/traefik/dynamic/panopticon.yml.template +41 -0
- package/templates/traefik/traefik.yml +8 -0
- package/dist/chunk-7HHDVXBM.js +0 -349
- package/dist/chunk-7HHDVXBM.js.map +0 -1
- package/dist/chunk-H45CLB7E.js +0 -2044
- package/dist/chunk-H45CLB7E.js.map +0 -1
- package/dist/chunk-ITI4IC5A.js.map +0 -1
- package/dist/dashboard/public/assets/index-BDd8hGYb.css +0 -32
- package/dist/dashboard/public/assets/index-sFwLPko-.js +0 -556
- package/templates/traefik/dynamic/panopticon.yml +0 -51
- /package/dist/{agents-B5NRTVHK.js.map → agents-54LDKMHR.js.map} +0 -0
package/README.md
CHANGED
|
@@ -55,6 +55,9 @@
|
|
|
55
55
|
| **Convoys** | Run parallel agents on related issues with auto-synthesis |
|
|
56
56
|
| **Specialists** | Dedicated review, test, and merge agents for quality control |
|
|
57
57
|
| **Heartbeat Monitoring** | Real-time agent activity tracking via Claude Code hooks |
|
|
58
|
+
| **Mission Control** | Unified monitoring view — see all active features, agent activity, and planning artifacts at a glance |
|
|
59
|
+
| **Shadow Engineering** | Monitor existing workflows before transitioning to AI-driven development |
|
|
60
|
+
| **Real-Time Dashboard** | Socket.io push with multi-layer caching (in-memory + SQLite) for instant loads |
|
|
58
61
|
| **Legacy Codebase Support** | AI self-monitoring skills that learn from your codebase |
|
|
59
62
|
|
|
60
63
|
## Supported Tools
|
|
@@ -195,7 +198,7 @@ The AI adapts to your org structure, not the other way around.
|
|
|
195
198
|
|
|
196
199
|
---
|
|
197
200
|
|
|
198
|
-
## Quick Start
|
|
201
|
+
## 🚀 Quick Start
|
|
199
202
|
|
|
200
203
|
```bash
|
|
201
204
|
npm install -g panopticon-cli && pan install && pan sync && pan up
|
|
@@ -203,2759 +206,145 @@ npm install -g panopticon-cli && pan install && pan sync && pan up
|
|
|
203
206
|
|
|
204
207
|
**That's it!** Dashboard runs at https://pan.localhost (or http://localhost:3010 if you skip HTTPS setup).
|
|
205
208
|
|
|
206
|
-
📖 **[Full
|
|
209
|
+
📖 **[Full documentation →](docs/INDEX.md)**
|
|
207
210
|
|
|
208
|
-
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## 📋 Requirements
|
|
209
214
|
|
|
210
215
|
### Required
|
|
211
216
|
- Node.js 18+
|
|
212
217
|
- Git (for worktree-based workspaces)
|
|
213
218
|
- Docker (for Traefik and workspace containers)
|
|
214
219
|
- tmux (for agent sessions)
|
|
215
|
-
- **
|
|
216
|
-
- **
|
|
217
|
-
- **GitLab CLI (`glab`)** - For GitLab integration (if using GitLab). [Install](https://gitlab.com/gitlab-org/cli)
|
|
220
|
+
- **GitHub CLI (`gh`)** or **GitLab CLI (`glab`)** for Git operations
|
|
221
|
+
- **ttyd** - Auto-installed by `pan install`
|
|
218
222
|
|
|
219
223
|
### Optional
|
|
220
224
|
- **mkcert** - For HTTPS certificates (recommended)
|
|
221
|
-
- **Linear API key** - For issue tracking
|
|
222
|
-
- **Beads CLI
|
|
223
|
-
- **Google Stitch MCP** - For AI-powered UI design integration (see below)
|
|
224
|
-
|
|
225
|
-
### Platform Support
|
|
226
|
-
|
|
227
|
-
The Panopticon dashboard includes terminal streaming, which requires a native binary (`node-pty`). Prebuilt binaries are available for:
|
|
228
|
-
|
|
229
|
-
| Platform | Architecture | Support |
|
|
230
|
-
|----------|-------------|---------|
|
|
231
|
-
| macOS | Intel (x64) | ✅ Prebuilt |
|
|
232
|
-
| macOS | Apple Silicon (arm64) | ✅ Prebuilt |
|
|
233
|
-
| Linux | x64 (glibc) | ✅ Prebuilt |
|
|
234
|
-
| Linux | arm64 (glibc) | ✅ Prebuilt |
|
|
235
|
-
| Linux | musl (Alpine) | ✅ Prebuilt |
|
|
236
|
-
| Windows | x64 | ✅ Prebuilt |
|
|
237
|
-
|
|
238
|
-
If a prebuilt binary is not available for your platform, node-gyp will automatically compile from source during installation (requires Python and build tools).
|
|
239
|
-
|
|
240
|
-
### Why CLI tools instead of API tokens?
|
|
241
|
-
|
|
242
|
-
Panopticon uses `gh` and `glab` CLIs instead of raw API tokens because:
|
|
243
|
-
- **Better auth**: OAuth tokens that auto-refresh (no expiring PATs)
|
|
244
|
-
- **Simpler setup**: `gh auth login` handles everything
|
|
245
|
-
- **Agent-friendly**: Agents can use them for PRs, merges, reviews
|
|
246
|
-
|
|
247
|
-
## Configuration
|
|
248
|
-
|
|
249
|
-
Create `~/.panopticon.env`:
|
|
250
|
-
|
|
251
|
-
```bash
|
|
252
|
-
LINEAR_API_KEY=lin_api_xxxxx
|
|
253
|
-
GITHUB_TOKEN=ghp_xxxxx # Optional: for GitHub-tracked projects
|
|
254
|
-
RALLY_API_KEY=_xxxxx # Optional: for Rally as secondary tracker
|
|
255
|
-
```
|
|
256
|
-
|
|
257
|
-
### Issue Trackers
|
|
258
|
-
|
|
259
|
-
Panopticon supports multiple issue trackers:
|
|
225
|
+
- **Linear API key** - For issue tracking
|
|
226
|
+
- **Beads CLI** - Auto-installed by `pan install`
|
|
260
227
|
|
|
261
|
-
|
|
262
|
-
|---------|------|---------------|
|
|
263
|
-
| **Linear** | Primary tracker | `LINEAR_API_KEY` in `.panopticon.env` |
|
|
264
|
-
| **GitHub Issues** | Secondary tracker | `GITHUB_TOKEN` or `gh auth login` |
|
|
265
|
-
| **GitLab Issues** | Secondary tracker | `glab auth login` |
|
|
266
|
-
| **Rally** | Secondary tracker | `RALLY_API_KEY` in `.panopticon.env` |
|
|
228
|
+
📖 **[Platform support and detailed requirements →](docs/USAGE.md#requirements)**
|
|
267
229
|
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
### Multi-Model Support
|
|
271
|
-
|
|
272
|
-
Panopticon integrates with [claude-code-router](https://github.com/musistudio/claude-code-router) to enable using multiple AI model providers alongside Anthropic models. Configure which models to use for different agent types and task complexities.
|
|
273
|
-
|
|
274
|
-
📖 **[Complete work types guide and configuration examples →](docs/WORK-TYPES.md)**
|
|
275
|
-
📋 **[Configuration file reference and presets →](docs/CONFIGURATION.md)**
|
|
276
|
-
🧠 **[Model recommendations for optimal cost/performance →](docs/MODEL_RECOMMENDATIONS.md)**
|
|
277
|
-
|
|
278
|
-
#### Supported Providers and Models
|
|
279
|
-
|
|
280
|
-
**Anthropic** (via Claude Code / Claude API)
|
|
281
|
-
- `claude-opus-4-5` - Most capable, best for planning and complex tasks
|
|
282
|
-
- `claude-sonnet-4-5` - Balanced performance and cost
|
|
283
|
-
- `claude-haiku-4-5` - Fast and cost-effective for simple tasks
|
|
284
|
-
|
|
285
|
-
**OpenAI**
|
|
286
|
-
- `gpt-5.2-codex` - Agentic coding and research
|
|
287
|
-
- `o3-deep-research` - Deep research capabilities
|
|
288
|
-
- `gpt-4o` - General-purpose model
|
|
289
|
-
- `gpt-4o-mini` - Faster, more cost-effective variant
|
|
290
|
-
|
|
291
|
-
**Google (Gemini)**
|
|
292
|
-
- `gemini-3-pro-preview` - Supports `thinking_level: high|low`
|
|
293
|
-
- `gemini-3-flash-preview` - Supports `thinking_level: minimal|low|medium|high`
|
|
294
|
-
|
|
295
|
-
**Z.AI**
|
|
296
|
-
- `glm-4.7` - General-purpose model
|
|
297
|
-
- `glm-4.7-flash` - Faster variant
|
|
298
|
-
|
|
299
|
-
#### Configuration via Dashboard
|
|
300
|
-
|
|
301
|
-
1. Open the Panopticon dashboard and navigate to **Settings**
|
|
302
|
-
2. Configure **API keys** for external providers:
|
|
303
|
-
- OpenAI API Key
|
|
304
|
-
- Google AI API Key
|
|
305
|
-
- Z.AI API Key
|
|
306
|
-
3. Configure **models per agent type**:
|
|
307
|
-
- Review Agent - Model for code review
|
|
308
|
-
- Test Agent - Model for running tests
|
|
309
|
-
- Merge Agent - Model for handling merges
|
|
310
|
-
- Planning Agent - Model for autonomous planning
|
|
311
|
-
4. Configure **models by task complexity** (for PAN-75):
|
|
312
|
-
- Trivial tasks → Cost-effective models (e.g., `claude-haiku-4-5`)
|
|
313
|
-
- Expert tasks → Most capable models (e.g., `claude-opus-4-5`)
|
|
314
|
-
|
|
315
|
-
**Configuration Files:**
|
|
316
|
-
|
|
317
|
-
Panopticon uses YAML-based configuration (new in v0.5+):
|
|
318
|
-
|
|
319
|
-
| File | Purpose |
|
|
320
|
-
|------|---------|
|
|
321
|
-
| `~/.panopticon/config.yaml` | Global model settings, provider enable/disable, API key references |
|
|
322
|
-
| `~/.panopticon.env` | API keys and sensitive credentials (auto-loaded) |
|
|
323
|
-
| `.panopticon.yaml` | Per-project config (optional, overrides global) |
|
|
230
|
+
---
|
|
324
231
|
|
|
325
|
-
|
|
326
|
-
```bash
|
|
327
|
-
chmod 600 ~/.panopticon/config.yaml ~/.panopticon.env
|
|
328
|
-
```
|
|
232
|
+
## 🔧 Configuration
|
|
329
233
|
|
|
330
|
-
**Environment Variables:** API keys are loaded from `~/.panopticon.env` at startup:
|
|
331
234
|
```bash
|
|
332
|
-
#
|
|
333
|
-
|
|
334
|
-
OPENAI_API_KEY="sk-..."
|
|
335
|
-
GOOGLE_AI_KEY="AIza..."
|
|
336
|
-
ZAI_API_KEY="..."
|
|
337
|
-
```
|
|
338
|
-
|
|
339
|
-
In `config.yaml`, reference them with `$` syntax:
|
|
340
|
-
```yaml
|
|
341
|
-
models:
|
|
342
|
-
providers:
|
|
343
|
-
kimi:
|
|
344
|
-
enabled: true
|
|
345
|
-
api_key: $KIMI_API_KEY
|
|
346
|
-
```
|
|
347
|
-
|
|
348
|
-
#### Router Configuration
|
|
349
|
-
|
|
350
|
-
**Panopticon owns the router configuration.** When you save settings in the dashboard, Panopticon automatically generates `~/.claude-code-router/config.json` with the appropriate provider and routing configuration. Manual edits to this file will be overwritten on the next settings change.
|
|
351
|
-
|
|
352
|
-
#### Example Use Cases
|
|
353
|
-
|
|
354
|
-
**Cost optimization:**
|
|
355
|
-
```
|
|
356
|
-
Specialist agents → claude-sonnet-4-5 (balanced)
|
|
357
|
-
Planning agent → claude-opus-4-5 (most capable)
|
|
358
|
-
Simple tasks → claude-haiku-4-5 (cost-effective)
|
|
359
|
-
```
|
|
360
|
-
|
|
361
|
-
**Multi-provider setup:**
|
|
362
|
-
```
|
|
363
|
-
Code review → gpt-4o (OpenAI's code understanding)
|
|
364
|
-
Testing → claude-sonnet-4-5 (Anthropic's reliability)
|
|
365
|
-
Planning → claude-opus-4-5 (Anthropic's reasoning)
|
|
366
|
-
```
|
|
235
|
+
# Create config file
|
|
236
|
+
~/.panopticon.env
|
|
367
237
|
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
Implementation → claude-sonnet-4-5 (Anthropic)
|
|
372
|
-
Code review → gemini-3-pro-preview (Google)
|
|
238
|
+
# Add API keys
|
|
239
|
+
LINEAR_API_KEY=lin_api_xxxxx
|
|
240
|
+
GITHUB_TOKEN=ghp_xxxxx # Optional
|
|
373
241
|
```
|
|
374
242
|
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
Register your local project directories so Panopticon knows where to create workspaces:
|
|
243
|
+
Register your projects:
|
|
378
244
|
|
|
379
245
|
```bash
|
|
380
|
-
# Register a project
|
|
381
246
|
pan project add /path/to/your/project --name myproject
|
|
382
|
-
|
|
383
|
-
# List registered projects
|
|
384
|
-
pan project list
|
|
385
|
-
```
|
|
386
|
-
|
|
387
|
-
### Map Linear Projects to Local Directories
|
|
388
|
-
|
|
389
|
-
If you have multiple Linear projects, configure which local directory each maps to. Create/edit `~/.panopticon/project-mappings.json`:
|
|
390
|
-
|
|
391
|
-
```json
|
|
392
|
-
[
|
|
393
|
-
{
|
|
394
|
-
"linearProjectId": "abc123",
|
|
395
|
-
"linearProjectName": "Mind Your Now",
|
|
396
|
-
"linearPrefix": "MIN",
|
|
397
|
-
"localPath": "/home/user/projects/myn"
|
|
398
|
-
},
|
|
399
|
-
{
|
|
400
|
-
"linearProjectId": "def456",
|
|
401
|
-
"linearProjectName": "Househunt",
|
|
402
|
-
"linearPrefix": "HH",
|
|
403
|
-
"localPath": "/home/user/projects/househunt"
|
|
404
|
-
}
|
|
405
|
-
]
|
|
406
|
-
```
|
|
407
|
-
|
|
408
|
-
The dashboard uses this mapping to determine where to create workspaces when you click "Create Workspace" or "Start Agent" for an issue.
|
|
409
|
-
|
|
410
|
-
## Google Stitch Integration
|
|
411
|
-
|
|
412
|
-
Panopticon integrates with [Google Stitch](https://stitch.withgoogle.com), Google's AI-powered UI design tool, enabling design-to-code workflows.
|
|
413
|
-
|
|
414
|
-
### What is Google Stitch?
|
|
415
|
-
|
|
416
|
-
Google Stitch generates production-ready UI designs from natural language prompts or image inputs. It's free (350 standard + 50 experimental generations/month) and requires only a Google account.
|
|
417
|
-
|
|
418
|
-
### Setup (Optional)
|
|
419
|
-
|
|
420
|
-
Use the `/pan-stitch` skill to set up the integration:
|
|
421
|
-
|
|
422
|
-
```bash
|
|
423
|
-
# Run the setup skill
|
|
424
|
-
/pan-stitch
|
|
425
|
-
|
|
426
|
-
# Or manually:
|
|
427
|
-
# 1. Install gcloud CLI
|
|
428
|
-
curl -sSL https://sdk.cloud.google.com | bash
|
|
429
|
-
|
|
430
|
-
# 2. Authenticate
|
|
431
|
-
gcloud auth login
|
|
432
|
-
gcloud auth application-default login
|
|
433
|
-
|
|
434
|
-
# 3. Create project and enable API
|
|
435
|
-
gcloud projects create stitch-tools-$(date +%s)
|
|
436
|
-
gcloud config set project YOUR_PROJECT_ID
|
|
437
|
-
gcloud billing projects link YOUR_PROJECT_ID --billing-account=YOUR_BILLING_ID
|
|
438
|
-
gcloud beta services mcp enable stitch.googleapis.com # MUST use beta!
|
|
439
|
-
|
|
440
|
-
# 4. Register MCP (note "proxy" subcommand)
|
|
441
|
-
claude mcp add -e GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID -s user stitch -- npx -y @_davideast/stitch-mcp proxy
|
|
442
247
|
```
|
|
443
248
|
|
|
444
|
-
|
|
249
|
+
📖 **[Complete configuration guide →](docs/CONFIGURATION.md)**
|
|
250
|
+
📖 **[Work types and model routing →](docs/WORK-TYPES.md)**
|
|
251
|
+
📖 **[Detailed usage examples →](docs/USAGE.md)**
|
|
445
252
|
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
1. **Create UI designs** - Generate screens for UI-related issues
|
|
449
|
-
2. **Document in STATE.md** - Record Stitch project/screen IDs for workers
|
|
450
|
-
3. **Worker agents pick up designs** - Use the Stitch skills to convert to React
|
|
451
|
-
|
|
452
|
-
### Bidirectional Sync
|
|
453
|
-
|
|
454
|
-
Designs are stored in your Google account and sync bidirectionally:
|
|
455
|
-
|
|
456
|
-
```
|
|
457
|
-
Planning Agent creates design via MCP
|
|
458
|
-
↓
|
|
459
|
-
Stored in Google Cloud (your account)
|
|
460
|
-
↓
|
|
461
|
-
Visible on stitch.withgoogle.com
|
|
462
|
-
↓
|
|
463
|
-
Worker agent retrieves via MCP → converts to React
|
|
464
|
-
```
|
|
465
|
-
|
|
466
|
-
- **MCP → Web UI:** Designs created by agents appear in Stitch web UI
|
|
467
|
-
- **Web UI → MCP:** Designs created in web UI are accessible to agents
|
|
468
|
-
- **Edit anywhere:** Refine AI-generated designs in the web UI before workers convert them
|
|
469
|
-
|
|
470
|
-
### Available MCP Tools
|
|
471
|
-
|
|
472
|
-
| Tool | Purpose |
|
|
473
|
-
|------|---------|
|
|
474
|
-
| `create_project` | Create a new Stitch project |
|
|
475
|
-
| `list_projects` | List all your projects (owned/shared) |
|
|
476
|
-
| `get_project` | Get project details |
|
|
477
|
-
| `list_screens` | List screens in a project |
|
|
478
|
-
| `get_screen` | Get screen details + HTML/CSS download URLs |
|
|
479
|
-
| `generate_screen_from_text` | Generate a screen from a text prompt |
|
|
480
|
-
|
|
481
|
-
### Stitch Skills
|
|
482
|
-
|
|
483
|
-
| Skill | Purpose |
|
|
484
|
-
|-------|---------|
|
|
485
|
-
| `/pan-stitch` | Setup and configure Stitch MCP |
|
|
486
|
-
| `/stitch-design-md` | Create DESIGN.md from Stitch projects |
|
|
487
|
-
| `/stitch-react-components` | Convert Stitch HTML to React components |
|
|
488
|
-
|
|
489
|
-
### STATE.md Integration
|
|
490
|
-
|
|
491
|
-
When planning UI work, add a Stitch section to STATE.md:
|
|
492
|
-
|
|
493
|
-
```markdown
|
|
494
|
-
## UI Designs
|
|
495
|
-
|
|
496
|
-
### Stitch Assets
|
|
497
|
-
- **Project ID:** 12345678
|
|
498
|
-
- **Screen:** "Dashboard" (screen ID: 87654321)
|
|
499
|
-
- **Design Notes:** Dark mode, glassmorphism cards, gradient accents
|
|
500
|
-
- **DESIGN.md:** Generated at `src/components/DESIGN.md`
|
|
501
|
-
|
|
502
|
-
Worker: Use `/stitch-react-components` to convert the Dashboard screen to React.
|
|
503
|
-
```
|
|
504
|
-
|
|
505
|
-
### Manual Workflow (No MCP)
|
|
506
|
-
|
|
507
|
-
If you prefer not to set up the MCP:
|
|
508
|
-
|
|
509
|
-
1. Design at https://stitch.withgoogle.com
|
|
510
|
-
2. Export HTML/CSS from the UI
|
|
511
|
-
3. Use `/stitch-react-components` with the exported files
|
|
512
|
-
|
|
513
|
-
## Cloister: AI Lifecycle Manager
|
|
514
|
-
|
|
515
|
-
Cloister is Panopticon's intelligent agent lifecycle manager. It monitors all running agents and automatically handles:
|
|
253
|
+
---
|
|
516
254
|
|
|
517
|
-
|
|
518
|
-
- **Stuck Detection** - Identifies agents that have stopped making progress
|
|
519
|
-
- **Automatic Handoffs** - Escalates to specialists when needed
|
|
520
|
-
- **Specialist Coordination** - Manages test-agent, review-agent, and merge-agent
|
|
255
|
+
## 🎯 Key Concepts
|
|
521
256
|
|
|
522
|
-
###
|
|
257
|
+
### Mission Control
|
|
258
|
+
The default landing view. A two-panel layout with a resizable sidebar showing your project tree (grouped by project, filtered to active features) and a main area displaying agent activity, planning artifacts (PRD, STATE.md, transcripts, discussions), and status reviews.
|
|
523
259
|
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
529
|
-
│ │ Heartbeat │───▶│ Trigger │───▶│ Handoff │ │
|
|
530
|
-
│ │ Monitor │ │ Detector │ │ Manager │ │
|
|
531
|
-
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|
532
|
-
│ │ │ │ │
|
|
533
|
-
│ ▼ ▼ ▼ │
|
|
534
|
-
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
535
|
-
│ │ Agent │ │ Complexity │ │ Specialists │ │
|
|
536
|
-
│ │ Health │ │ Analysis │ │ │ │
|
|
537
|
-
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|
538
|
-
└─────────────────────────────────────────────────────────────┘
|
|
539
|
-
```
|
|
260
|
+
- **Project Tree**: Features grouped by project with live state labels (In Progress, Suspended, In Review, Done, Planning, Idle)
|
|
261
|
+
- **Activity View**: Chronological agent sessions with tail-anchored scrolling — click a feature and see what the agent is doing right now
|
|
262
|
+
- **Badge Bar**: Quick access to PRD, STATE.md, discussions, transcripts, status reviews, and file uploads
|
|
263
|
+
- **Status Reviews**: On-demand AI-generated progress reports comparing code changes against the PRD
|
|
540
264
|
|
|
541
|
-
###
|
|
265
|
+
### Shadow Engineering
|
|
266
|
+
A mode for teams adopting AI incrementally. Register existing projects as "shadow" workspaces to monitor ongoing development without AI agents making changes.
|
|
542
267
|
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
268
|
+
- Create shadow features with `pan workspace create --shadow PAN-XXX`
|
|
269
|
+
- Upload meeting transcripts and notes via the Badge Bar
|
|
270
|
+
- Sync issue tracker discussions automatically
|
|
271
|
+
- Generate inference documents (INFERENCE.md) analyzing how AI would approach the work
|
|
272
|
+
- Transition from monitoring to AI-driven development when ready
|
|
547
273
|
|
|
548
|
-
|
|
549
|
-
|
|
274
|
+
### Multi-Agent Orchestration
|
|
275
|
+
Spawn and manage AI agents in tmux sessions, monitored by the Cloister lifecycle manager.
|
|
550
276
|
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
```
|
|
277
|
+
### Workspaces
|
|
278
|
+
Git worktree-based feature branches with optional Docker isolation. Supports both local and remote (exe.dev) execution.
|
|
554
279
|
|
|
555
280
|
### Specialists
|
|
281
|
+
Dedicated agents for code review, testing, and merging. Automatically triggered by the Cloister manager.
|
|
556
282
|
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
| Specialist | Purpose | Trigger |
|
|
560
|
-
|------------|---------|---------|
|
|
561
|
-
| **test-agent** | Runs test suite after implementation | `implementation_complete` signal |
|
|
562
|
-
| **review-agent** | Code review before merge | After tests pass (manual trigger) |
|
|
563
|
-
| **merge-agent** | Handles git merge and conflict resolution | "Approve & Merge" button |
|
|
564
|
-
|
|
565
|
-
#### Merge Agent Workflow
|
|
566
|
-
|
|
567
|
-
The merge-agent is a specialist that handles **ALL** merges, not just conflicts. This ensures:
|
|
568
|
-
- It sees all code changes coming through the pipeline
|
|
569
|
-
- It builds context about the codebase over time
|
|
570
|
-
- When conflicts DO occur, it has better understanding for intelligent resolution
|
|
571
|
-
- Tests are always run before completing the merge
|
|
572
|
-
|
|
573
|
-
**Workflow:**
|
|
283
|
+
### Skills
|
|
284
|
+
Universal SKILL.md format works across Claude Code, Codex, Cursor, and Gemini. Distributed via `pan sync`.
|
|
574
285
|
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
3. **Perform merge** - Merges feature branch into main
|
|
578
|
-
4. **Resolve conflicts** - If conflicts exist, uses AI to resolve them intelligently
|
|
579
|
-
5. **Run tests** - Verifies the merge didn't break anything
|
|
580
|
-
6. **Commit merge** - Commits the merge with descriptive message
|
|
581
|
-
7. **Report results** - Returns success/failure with details
|
|
286
|
+
📖 **[Architecture overview →](AGENTS.md)**
|
|
287
|
+
📖 **[Specialist workflow →](docs/SPECIALIST_WORKFLOW.md)**
|
|
582
288
|
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
```bash
|
|
586
|
-
# Via dashboard - click "Approve & Merge" on an issue card
|
|
587
|
-
# merge-agent is ALWAYS invoked, regardless of whether conflicts exist
|
|
588
|
-
|
|
589
|
-
# Via CLI
|
|
590
|
-
pan specialists wake merge-agent --issue MIN-123
|
|
591
|
-
```
|
|
592
|
-
|
|
593
|
-
The merge-agent uses a specialized prompt template that instructs it to:
|
|
594
|
-
- Never force-push
|
|
595
|
-
- Always run tests before completing
|
|
596
|
-
- Document conflict resolution decisions
|
|
597
|
-
- Provide detailed feedback on what was merged
|
|
598
|
-
|
|
599
|
-
#### Review Pipeline Flow
|
|
600
|
-
|
|
601
|
-
The review pipeline is a sequential handoff between specialists:
|
|
602
|
-
|
|
603
|
-
```
|
|
604
|
-
Human clicks "Review"
|
|
605
|
-
│
|
|
606
|
-
▼
|
|
607
|
-
┌───────────────────┐
|
|
608
|
-
│ review-agent │ Reviews code, checks for issues
|
|
609
|
-
└─────────┬─────────┘
|
|
610
|
-
│ If PASSED: queues test-agent
|
|
611
|
-
│ If BLOCKED: sends feedback to work-agent
|
|
612
|
-
▼
|
|
613
|
-
┌───────────────────┐
|
|
614
|
-
│ test-agent │ Runs test suite, analyzes failures
|
|
615
|
-
└─────────┬─────────┘
|
|
616
|
-
│ If PASSED: marks ready for merge
|
|
617
|
-
│ If FAILED: sends feedback to work-agent
|
|
618
|
-
▼
|
|
619
|
-
┌───────────────────┐
|
|
620
|
-
│ (Human clicks │ Human approval required
|
|
621
|
-
│ "Approve & Merge"│ before merge
|
|
622
|
-
└─────────┬─────────┘
|
|
623
|
-
▼
|
|
624
|
-
┌───────────────────┐
|
|
625
|
-
│ merge-agent │ Performs merge, resolves conflicts
|
|
626
|
-
└───────────────────┘
|
|
627
|
-
```
|
|
628
|
-
|
|
629
|
-
**Key Points:**
|
|
630
|
-
- **Human-initiated start** - A human must click "Review" to start the pipeline
|
|
631
|
-
- **Automatic handoffs** - review-agent → test-agent happens automatically
|
|
632
|
-
- **Human approval for merge** - Merge is NOT automatic; human clicks "Approve & Merge"
|
|
633
|
-
- **Feedback loops** - Failed reviews/tests send feedback back to the work-agent
|
|
634
|
-
|
|
635
|
-
#### Queue Processing
|
|
636
|
-
|
|
637
|
-
Each specialist has a task queue (`~/.panopticon/specialists/{name}/hook.json`) managed via the FPP (Fixed Point Principle):
|
|
638
|
-
|
|
639
|
-
```
|
|
640
|
-
1. Task arrives (via API or handoff)
|
|
641
|
-
│
|
|
642
|
-
▼
|
|
643
|
-
2. wakeSpecialistOrQueue() checks if specialist is busy
|
|
644
|
-
│
|
|
645
|
-
├── If IDLE: Wake specialist immediately with task
|
|
646
|
-
│
|
|
647
|
-
└── If BUSY: Add task to queue (hook.json)
|
|
648
|
-
│
|
|
649
|
-
▼
|
|
650
|
-
3. When specialist completes current task:
|
|
651
|
-
│
|
|
652
|
-
├── Updates status via API (passed/failed/skipped)
|
|
653
|
-
│
|
|
654
|
-
└── Dashboard automatically wakes specialist for next queued task
|
|
655
|
-
```
|
|
656
|
-
|
|
657
|
-
**Queue priority order:** `urgent` > `high` > `normal` > `low`
|
|
658
|
-
|
|
659
|
-
**Completion triggers:** When a specialist reports status (`passed`, `failed`, or `skipped`), the dashboard:
|
|
660
|
-
1. Sets the specialist state to `idle`
|
|
661
|
-
2. Checks the specialist's queue for pending work
|
|
662
|
-
3. If work exists, immediately wakes the specialist with the next task
|
|
663
|
-
|
|
664
|
-
#### Agent Self-Requeue (Circuit Breaker)
|
|
289
|
+
---
|
|
665
290
|
|
|
666
|
-
|
|
291
|
+
## 🛠️ Common Commands
|
|
667
292
|
|
|
668
293
|
```bash
|
|
669
|
-
#
|
|
670
|
-
pan
|
|
671
|
-
```
|
|
672
|
-
|
|
673
|
-
**Circuit breaker behavior:**
|
|
674
|
-
- First human click resets the counter to 0
|
|
675
|
-
- Each `pan work request-review` increments the counter
|
|
676
|
-
- After 3 automatic re-requests, returns HTTP 429
|
|
677
|
-
- Human must click "Review" in dashboard to continue
|
|
678
|
-
|
|
679
|
-
This prevents infinite loops where an agent repeatedly fails review.
|
|
680
|
-
|
|
681
|
-
**API endpoint:** `POST /api/workspaces/:issueId/request-review`
|
|
682
|
-
|
|
683
|
-
#### Specialist Auto-Initialization
|
|
684
|
-
|
|
685
|
-
When Cloister starts, it automatically initializes specialists that don't exist yet. This ensures the test-agent, review-agent, and merge-agent are ready to receive wake signals without manual setup.
|
|
686
|
-
|
|
687
|
-
### Automatic Handoffs
|
|
688
|
-
|
|
689
|
-
Cloister detects situations that require intervention:
|
|
690
|
-
|
|
691
|
-
| Trigger | Condition | Action |
|
|
692
|
-
|---------|-----------|--------|
|
|
693
|
-
| **stuck_escalation** | No activity for 30+ minutes | Escalate to more capable model |
|
|
694
|
-
| **complexity_upgrade** | Task complexity exceeds model capability | Route to Opus |
|
|
695
|
-
| **implementation_complete** | Agent signals work is done | Wake test-agent |
|
|
696
|
-
| **test_failure** | Tests fail repeatedly | Escalate model or request help |
|
|
697
|
-
| **planning_complete** | Planning session finishes | Transition to implementation |
|
|
698
|
-
| **merge_requested** | User clicks "Approve & Merge" | Wake merge-agent |
|
|
699
|
-
|
|
700
|
-
### Handoff Methods
|
|
701
|
-
|
|
702
|
-
Cloister supports two handoff methods, automatically selected based on agent type:
|
|
703
|
-
|
|
704
|
-
| Method | When Used | How It Works |
|
|
705
|
-
|--------|-----------|--------------|
|
|
706
|
-
| **Kill & Spawn** | General agents (agent-min-123, etc.) | 1. Captures full context (STATE.md, beads, git state)<br>2. Kills tmux session<br>3. Spawns new agent with handoff prompt<br>4. New agent continues work with preserved context |
|
|
707
|
-
| **Specialist Wake** | Permanent specialists (merge-agent, test-agent) | 1. Captures handoff context<br>2. Sends wake message to existing session<br>3. Specialist resumes with context injection |
|
|
708
|
-
|
|
709
|
-
**Kill & Spawn** is used for temporary agents that work on specific issues. It creates a clean handoff by:
|
|
710
|
-
- Capturing the agent's current understanding (from STATE.md)
|
|
711
|
-
- Preserving beads task progress and open items
|
|
712
|
-
- Including relevant git diff and file context
|
|
713
|
-
- Building a comprehensive handoff prompt for the new model
|
|
714
|
-
|
|
715
|
-
**Specialist Wake** is used for permanent specialists that persist across multiple issues. It avoids the overhead of killing/respawning by injecting context into the existing session.
|
|
716
|
-
|
|
717
|
-
### Handoff Context Capture
|
|
718
|
-
|
|
719
|
-
When a handoff occurs, Cloister captures:
|
|
720
|
-
|
|
721
|
-
```json
|
|
722
|
-
{
|
|
723
|
-
"agentId": "agent-min-123",
|
|
724
|
-
"issueId": "MIN-123",
|
|
725
|
-
"currentModel": "sonnet",
|
|
726
|
-
"targetModel": "opus",
|
|
727
|
-
"reason": "stuck_escalation",
|
|
728
|
-
"handoffCount": 1,
|
|
729
|
-
"state": {
|
|
730
|
-
"phase": "implementation",
|
|
731
|
-
"complexity": "complex",
|
|
732
|
-
"lastActivity": "2024-01-22T10:30:00-08:00"
|
|
733
|
-
},
|
|
734
|
-
"beadsTasks": [...],
|
|
735
|
-
"gitContext": {
|
|
736
|
-
"branch": "feature/min-123",
|
|
737
|
-
"uncommittedChanges": ["src/auth.ts", "src/tests/auth.test.ts"],
|
|
738
|
-
"recentCommits": [...]
|
|
739
|
-
}
|
|
740
|
-
}
|
|
741
|
-
```
|
|
742
|
-
|
|
743
|
-
Handoff prompts are saved to `~/.panopticon/agents/{agent-id}/handoffs/` for debugging.
|
|
744
|
-
|
|
745
|
-
### Heartbeat Monitoring
|
|
746
|
-
|
|
747
|
-
Agents send heartbeats via Claude Code hooks. Cloister tracks:
|
|
748
|
-
|
|
749
|
-
- Last tool use and timestamp
|
|
750
|
-
- Current task being worked on
|
|
751
|
-
- Git branch and workspace
|
|
752
|
-
- Process health
|
|
753
|
-
|
|
754
|
-
Heartbeat files are stored in `~/.panopticon/heartbeats/`:
|
|
755
|
-
|
|
756
|
-
```json
|
|
757
|
-
{
|
|
758
|
-
"timestamp": "2024-01-22T10:30:00-08:00",
|
|
759
|
-
"agent_id": "agent-min-123",
|
|
760
|
-
"tool_name": "Edit",
|
|
761
|
-
"last_action": "{\"file_path\":\"/path/to/file.ts\"...}",
|
|
762
|
-
"git_branch": "feature/min-123",
|
|
763
|
-
"workspace": "/home/user/projects/myapp/workspaces/feature-min-123"
|
|
764
|
-
}
|
|
765
|
-
```
|
|
294
|
+
# Start dashboard
|
|
295
|
+
pan up
|
|
766
296
|
|
|
767
|
-
|
|
297
|
+
# Create workspace and spawn agent
|
|
298
|
+
pan workspace create PAN-123
|
|
768
299
|
|
|
769
|
-
|
|
300
|
+
# Check agent status
|
|
301
|
+
pan status
|
|
770
302
|
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
pan sync # Syncs all skills, agents, AND hooks
|
|
774
|
-
```
|
|
303
|
+
# View agent logs
|
|
304
|
+
pan logs agent-pan-123
|
|
775
305
|
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
{
|
|
779
|
-
"hooks": {
|
|
780
|
-
"PostToolUse": [
|
|
781
|
-
{
|
|
782
|
-
"matcher": "*",
|
|
783
|
-
"hooks": [
|
|
784
|
-
{
|
|
785
|
-
"type": "command",
|
|
786
|
-
"command": "~/.panopticon/bin/heartbeat-hook"
|
|
787
|
-
}
|
|
788
|
-
]
|
|
789
|
-
}
|
|
790
|
-
]
|
|
791
|
-
}
|
|
792
|
-
}
|
|
306
|
+
# Stop dashboard
|
|
307
|
+
pan down
|
|
793
308
|
```
|
|
794
309
|
|
|
795
|
-
**
|
|
796
|
-
- The heartbeats directory doesn't exist
|
|
797
|
-
- Write permissions are missing
|
|
798
|
-
- The hook script has errors
|
|
799
|
-
|
|
800
|
-
This prevents hook failures from interrupting agent work.
|
|
801
|
-
|
|
802
|
-
### Configuration
|
|
803
|
-
|
|
804
|
-
Cloister configuration lives in `~/.panopticon/cloister/config.json`:
|
|
805
|
-
|
|
806
|
-
```json
|
|
807
|
-
{
|
|
808
|
-
"monitoring": {
|
|
809
|
-
"heartbeat_interval_ms": 5000,
|
|
810
|
-
"stuck_threshold_minutes": 30,
|
|
811
|
-
"health_check_interval_ms": 30000
|
|
812
|
-
},
|
|
813
|
-
"specialists": {
|
|
814
|
-
"test_agent": { "enabled": true, "auto_wake": true },
|
|
815
|
-
"review_agent": { "enabled": true, "auto_wake": false },
|
|
816
|
-
"merge_agent": { "enabled": true, "auto_wake": false }
|
|
817
|
-
},
|
|
818
|
-
"triggers": {
|
|
819
|
-
"stuck_escalation": { "enabled": true },
|
|
820
|
-
"complexity_upgrade": { "enabled": true }
|
|
821
|
-
}
|
|
822
|
-
}
|
|
823
|
-
```
|
|
310
|
+
📖 **[Complete command reference →](docs/USAGE.md#commands)**
|
|
824
311
|
|
|
825
312
|
---
|
|
826
313
|
|
|
827
|
-
##
|
|
828
|
-
|
|
829
|
-
Cloister automatically routes tasks to the appropriate model based on detected complexity, optimizing for cost while ensuring quality.
|
|
830
|
-
|
|
831
|
-
### Complexity Levels
|
|
832
|
-
|
|
833
|
-
| Level | Model | Use Case |
|
|
834
|
-
|-------|-------|----------|
|
|
835
|
-
| **trivial** | Haiku | Typos, comments, documentation updates |
|
|
836
|
-
| **simple** | Haiku | Small fixes, test additions, minor changes |
|
|
837
|
-
| **medium** | Sonnet | Features, components, integrations |
|
|
838
|
-
| **complex** | Sonnet/Opus | Refactors, migrations, redesigns |
|
|
839
|
-
| **expert** | Opus | Architecture, security, performance optimization |
|
|
840
|
-
|
|
841
|
-
### Complexity Detection Signals
|
|
842
|
-
|
|
843
|
-
Complexity is detected from multiple signals (in priority order):
|
|
844
|
-
|
|
845
|
-
1. **Explicit field** - Task has a `complexity` field set (e.g., in beads)
|
|
846
|
-
2. **Labels/tags** - Issue labels like `architecture`, `security`, `refactor`
|
|
847
|
-
3. **Keywords** - Title/description contains keywords like "migration", "overhaul"
|
|
848
|
-
4. **File count** - Number of files changed (>20 files = complex)
|
|
849
|
-
5. **Time estimate** - If estimate exceeds thresholds
|
|
314
|
+
## 📚 Documentation
|
|
850
315
|
|
|
851
|
-
|
|
852
|
-
|
|
853
|
-
|
|
854
|
-
|
|
855
|
-
|
|
856
|
-
|
|
857
|
-
|
|
858
|
-
|
|
859
|
-
|
|
860
|
-
|
|
861
|
-
|
|
862
|
-
### Configuring Model Routing
|
|
863
|
-
|
|
864
|
-
Edit `~/.panopticon/cloister/config.json`:
|
|
865
|
-
|
|
866
|
-
```json
|
|
867
|
-
{
|
|
868
|
-
"model_selection": {
|
|
869
|
-
"default_model": "sonnet",
|
|
870
|
-
"complexity_routing": {
|
|
871
|
-
"trivial": "haiku",
|
|
872
|
-
"simple": "haiku",
|
|
873
|
-
"medium": "sonnet",
|
|
874
|
-
"complex": "sonnet",
|
|
875
|
-
"expert": "opus"
|
|
876
|
-
}
|
|
877
|
-
}
|
|
878
|
-
}
|
|
879
|
-
```
|
|
880
|
-
|
|
881
|
-
### Cost Optimization
|
|
882
|
-
|
|
883
|
-
Model routing helps optimize costs:
|
|
884
|
-
|
|
885
|
-
| Model | Relative Cost | Best For |
|
|
886
|
-
|-------|---------------|----------|
|
|
887
|
-
| Haiku | 1x (cheapest) | Simple tasks, bulk operations |
|
|
888
|
-
| Sonnet | 3x | Most development work |
|
|
889
|
-
| Opus | 15x | Complex architecture, critical fixes |
|
|
890
|
-
|
|
891
|
-
A typical agent run might:
|
|
892
|
-
1. Start on Haiku for initial exploration
|
|
893
|
-
2. Escalate to Sonnet for implementation
|
|
894
|
-
3. Escalate to Opus only if stuck or complexity detected
|
|
316
|
+
| Document | Description |
|
|
317
|
+
|----------|-------------|
|
|
318
|
+
| [docs/INDEX.md](docs/INDEX.md) | Master documentation index (start here) |
|
|
319
|
+
| [docs/USAGE.md](docs/USAGE.md) | Detailed usage guide, examples, troubleshooting |
|
|
320
|
+
| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | Model routing, API setup, presets |
|
|
321
|
+
| [AGENTS.md](AGENTS.md) | Agent architecture |
|
|
322
|
+
| [docs/ARCHITECTURE-CACHING.md](docs/ARCHITECTURE-CACHING.md) | Dashboard caching and real-time push |
|
|
323
|
+
| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution guidelines |
|
|
324
|
+
| [CLAUDE.md](CLAUDE.md) | Agent development guidance |
|
|
325
|
+
| [docs/MISSION-CONTROL.md](docs/MISSION-CONTROL.md) | Mission Control and Shadow Engineering guide |
|
|
895
326
|
|
|
896
327
|
---
|
|
897
328
|
|
|
898
|
-
##
|
|
899
|
-
|
|
900
|
-
Panopticon supports managing multiple projects with intelligent issue routing.
|
|
901
|
-
|
|
902
|
-
### Project Registry
|
|
903
|
-
|
|
904
|
-
Projects are registered in `~/.panopticon/projects.yaml`:
|
|
905
|
-
|
|
906
|
-
```yaml
|
|
907
|
-
projects:
|
|
908
|
-
myn:
|
|
909
|
-
name: "Mind Your Now"
|
|
910
|
-
path: /home/user/projects/myn
|
|
911
|
-
linear_team: MIN
|
|
912
|
-
issue_routing:
|
|
913
|
-
- labels: [splash, landing-pages, seo]
|
|
914
|
-
path: /home/user/projects/myn/splash
|
|
915
|
-
- labels: [docs, marketing]
|
|
916
|
-
path: /home/user/projects/myn/docs
|
|
917
|
-
- default: true
|
|
918
|
-
path: /home/user/projects/myn
|
|
919
|
-
|
|
920
|
-
panopticon:
|
|
921
|
-
name: "Panopticon"
|
|
922
|
-
path: /home/user/projects/panopticon
|
|
923
|
-
linear_team: PAN
|
|
924
|
-
```
|
|
925
|
-
|
|
926
|
-
### Label-Based Routing
|
|
927
|
-
|
|
928
|
-
Issues are routed to different subdirectories based on their labels:
|
|
929
|
-
|
|
930
|
-
1. **Labeled issues** - Matched against `issue_routing` rules in order
|
|
931
|
-
2. **Default route** - Issues without matching labels use the `default: true` path
|
|
932
|
-
3. **Fallback** - If no default, uses the project root path
|
|
933
|
-
|
|
934
|
-
Example: An issue with label "splash" in the MIN team would create its workspace at `/home/user/projects/myn/splash/workspaces/feature-min-xxx/`.
|
|
935
|
-
|
|
936
|
-
### Custom Workspace Commands (Legacy)
|
|
937
|
-
|
|
938
|
-
> **Note:** For most polyrepo projects, use the built-in `workspace` configuration (see below) instead of custom scripts. Custom commands are only needed for highly specialized setups.
|
|
939
|
-
|
|
940
|
-
For projects that need logic beyond what the configuration supports, you can specify custom workspace scripts:
|
|
941
|
-
|
|
942
|
-
```yaml
|
|
943
|
-
projects:
|
|
944
|
-
myn:
|
|
945
|
-
name: "Mind Your Now"
|
|
946
|
-
path: /home/user/projects/myn
|
|
947
|
-
linear_team: MIN
|
|
948
|
-
# Custom scripts handle complex workspace setup
|
|
949
|
-
workspace_command: /home/user/projects/myn/infra/new-feature
|
|
950
|
-
workspace_remove_command: /home/user/projects/myn/infra/remove-feature
|
|
951
|
-
```
|
|
952
|
-
|
|
953
|
-
When `workspace_command` is specified, Panopticon calls your script instead of creating a standard git worktree. The script receives the normalized issue ID (e.g., `min-123`) as an argument.
|
|
954
|
-
|
|
955
|
-
When `workspace_remove_command` is specified, Panopticon calls your script when deleting workspaces (e.g., aborting planning with "delete workspace" enabled). This is important for complex setups that need to:
|
|
956
|
-
- Stop Docker containers and remove volumes
|
|
957
|
-
- Clean up root-owned files created by containers
|
|
958
|
-
- Remove git worktrees from multiple repositories
|
|
959
|
-
- Release port assignments
|
|
960
|
-
- Remove DNS entries
|
|
961
|
-
|
|
962
|
-
**What your custom script should handle:**
|
|
963
|
-
- Creating git worktrees for multiple repositories (polyrepo structure)
|
|
964
|
-
- Setting up Docker Compose files and dev containers
|
|
965
|
-
- Configuring environment variables and `.env` files
|
|
966
|
-
- Setting up DNS entries for workspace-specific URLs (e.g., Traefik routing)
|
|
967
|
-
- Creating a `./dev` script for container management
|
|
968
|
-
- Copying agent configuration templates (CLAUDE.md, .mcp.json, etc.)
|
|
969
|
-
|
|
970
|
-
**Example script flow:**
|
|
971
|
-
```bash
|
|
972
|
-
#!/bin/bash
|
|
973
|
-
# new-feature script for a polyrepo project
|
|
974
|
-
ISSUE_ID=$1 # e.g., "min-123"
|
|
975
|
-
|
|
976
|
-
# Create worktrees for frontend and api repos
|
|
977
|
-
git -C /path/to/frontend worktree add ../workspaces/feature-$ISSUE_ID/fe feature/$ISSUE_ID
|
|
978
|
-
git -C /path/to/api worktree add ../workspaces/feature-$ISSUE_ID/api feature/$ISSUE_ID
|
|
979
|
-
|
|
980
|
-
# Generate docker-compose from templates
|
|
981
|
-
sed "s/{{FEATURE_FOLDER}}/feature-$ISSUE_ID/g" template.yml > workspace/docker-compose.yml
|
|
982
|
-
|
|
983
|
-
# Set up DNS and Traefik routing
|
|
984
|
-
# ... additional setup
|
|
985
|
-
```
|
|
986
|
-
|
|
987
|
-
The standard `pan workspace create` command will automatically detect and use your custom script.
|
|
988
|
-
|
|
989
|
-
#### Container Configuration Tips
|
|
990
|
-
|
|
991
|
-
When setting up Docker containers for workspaces, avoid these common pitfalls:
|
|
992
|
-
|
|
993
|
-
**Maven projects:**
|
|
994
|
-
- DO NOT set `MAVEN_CONFIG=/some/path` as an environment variable
|
|
995
|
-
- Maven interprets `MAVEN_CONFIG` as additional CLI arguments, not a directory path
|
|
996
|
-
- This causes "Unknown lifecycle phase" errors (e.g., "Unknown lifecycle phase /maven-cache")
|
|
997
|
-
- Instead, use `-Dmaven.repo.local=/path/to/cache` in the Maven command
|
|
998
|
-
|
|
999
|
-
```yaml
|
|
1000
|
-
# WRONG - causes Maven startup failure
|
|
1001
|
-
environment:
|
|
1002
|
-
- MAVEN_CONFIG=/maven-cache
|
|
1003
|
-
|
|
1004
|
-
# CORRECT - use command line argument
|
|
1005
|
-
command: ./mvnw spring-boot:run -Dmaven.repo.local=/maven-cache/repository
|
|
1006
|
-
volumes:
|
|
1007
|
-
- ~/.m2:/maven-cache:cached
|
|
1008
|
-
```
|
|
1009
|
-
|
|
1010
|
-
**pnpm projects:**
|
|
1011
|
-
- Set `PNPM_HOME=/path` to configure the pnpm store location
|
|
1012
|
-
- Mount a named volume for the store to share across containers
|
|
1013
|
-
|
|
1014
|
-
### What Your Project Needs to Provide
|
|
1015
|
-
|
|
1016
|
-
Panopticon is an orchestration layer - it manages workspaces, agents, and workflows, but **your project repository provides the actual templates and configuration**.
|
|
1017
|
-
|
|
1018
|
-
Projects can be as simple as just a git repo (for worktree-only workspaces) or as complex as a full polyrepo with Docker, Traefik, and database seeding. Here's what you need for each level:
|
|
1019
|
-
|
|
1020
|
-
### Required: Workspace Templates
|
|
1021
|
-
|
|
1022
|
-
Your project needs a `.devcontainer/` or template directory with:
|
|
1023
|
-
|
|
1024
|
-
```
|
|
1025
|
-
your-project/
|
|
1026
|
-
├── infra/
|
|
1027
|
-
│ └── .devcontainer-template/ # Template for workspace containers
|
|
1028
|
-
│ ├── docker-compose.devcontainer.yml.template
|
|
1029
|
-
│ ├── compose.infra.yml.template # Optional: separate infra services
|
|
1030
|
-
│ ├── Dockerfile
|
|
1031
|
-
│ └── devcontainer.json.template
|
|
1032
|
-
└── ...
|
|
1033
|
-
```
|
|
1034
|
-
|
|
1035
|
-
**Docker Compose templates** should use placeholders that Panopticon will replace:
|
|
1036
|
-
|
|
1037
|
-
```yaml
|
|
1038
|
-
# docker-compose.devcontainer.yml.template
|
|
1039
|
-
services:
|
|
1040
|
-
api:
|
|
1041
|
-
build: ./api
|
|
1042
|
-
user: vscode # Run as non-root to avoid permission issues
|
|
1043
|
-
labels:
|
|
1044
|
-
- "traefik.http.routers.{{FEATURE_FOLDER}}-api.rule=Host(`api-{{FEATURE_FOLDER}}.{{DOMAIN}}`)"
|
|
1045
|
-
environment:
|
|
1046
|
-
- DATABASE_URL=postgres://app:app@postgres:5432/mydb
|
|
1047
|
-
|
|
1048
|
-
frontend:
|
|
1049
|
-
build: ./fe
|
|
1050
|
-
user: vscode # Run as non-root to avoid permission issues
|
|
1051
|
-
labels:
|
|
1052
|
-
- "traefik.http.routers.{{FEATURE_FOLDER}}.rule=Host(`{{FEATURE_FOLDER}}.{{DOMAIN}}`)"
|
|
1053
|
-
```
|
|
1054
|
-
|
|
1055
|
-
> **⚠️ Important: File Permissions**
|
|
1056
|
-
>
|
|
1057
|
-
> Always run containers as a non-root user (e.g., `user: vscode`) to avoid permission issues.
|
|
1058
|
-
> Files created by root-owned containers cannot be removed by `pan workspace destroy` without sudo.
|
|
1059
|
-
> The Microsoft devcontainers base image includes a `vscode` user (UID 1000) that matches most host users.
|
|
1060
|
-
|
|
1061
|
-
### Required for HTTPS: Traefik Configuration
|
|
1062
|
-
|
|
1063
|
-
If you want local HTTPS (recommended), provide a Traefik compose file:
|
|
1064
|
-
|
|
1065
|
-
```
|
|
1066
|
-
your-project/
|
|
1067
|
-
├── infra/
|
|
1068
|
-
│ └── docker-compose.traefik.yml # Traefik reverse proxy
|
|
1069
|
-
└── ...
|
|
1070
|
-
```
|
|
1071
|
-
|
|
1072
|
-
Example Traefik config:
|
|
1073
|
-
```yaml
|
|
1074
|
-
# infra/docker-compose.traefik.yml
|
|
1075
|
-
services:
|
|
1076
|
-
traefik:
|
|
1077
|
-
image: traefik:v2.10
|
|
1078
|
-
ports:
|
|
1079
|
-
- "80:80"
|
|
1080
|
-
- "443:443"
|
|
1081
|
-
volumes:
|
|
1082
|
-
- /var/run/docker.sock:/var/run/docker.sock:ro
|
|
1083
|
-
- ~/.panopticon/traefik/certs:/certs:ro
|
|
1084
|
-
command:
|
|
1085
|
-
- --providers.docker=true
|
|
1086
|
-
- --entrypoints.web.address=:80
|
|
1087
|
-
- --entrypoints.websecure.address=:443
|
|
1088
|
-
```
|
|
1089
|
-
|
|
1090
|
-
### Required for Database Seeding: Seed Directory
|
|
1091
|
-
|
|
1092
|
-
For projects with databases:
|
|
1093
|
-
|
|
1094
|
-
```
|
|
1095
|
-
your-project/
|
|
1096
|
-
├── infra/
|
|
1097
|
-
│ └── seed/
|
|
1098
|
-
│ └── seed.sql # Sanitized production data
|
|
1099
|
-
└── ...
|
|
1100
|
-
```
|
|
1101
|
-
|
|
1102
|
-
Your compose template should mount this:
|
|
1103
|
-
```yaml
|
|
1104
|
-
services:
|
|
1105
|
-
postgres:
|
|
1106
|
-
image: postgres:16
|
|
1107
|
-
volumes:
|
|
1108
|
-
- /path/to/project/infra/seed:/docker-entrypoint-initdb.d:ro
|
|
1109
|
-
```
|
|
1110
|
-
|
|
1111
|
-
### Optional: Agent Templates
|
|
1112
|
-
|
|
1113
|
-
For customizing how agents work in your project:
|
|
1114
|
-
|
|
1115
|
-
```
|
|
1116
|
-
your-project/
|
|
1117
|
-
├── infra/
|
|
1118
|
-
│ └── .agent-template/
|
|
1119
|
-
│ ├── CLAUDE.md.template # Project-specific AI instructions
|
|
1120
|
-
│ └── .mcp.json.template # MCP server configuration
|
|
1121
|
-
└── .claude/
|
|
1122
|
-
└── skills/ # Project-specific skills
|
|
1123
|
-
└── my-project-standards/
|
|
1124
|
-
└── SKILL.md
|
|
1125
|
-
```
|
|
1126
|
-
|
|
1127
|
-
### Configuration in projects.yaml
|
|
1128
|
-
|
|
1129
|
-
Point Panopticon to your templates:
|
|
1130
|
-
|
|
1131
|
-
```yaml
|
|
1132
|
-
# ~/.panopticon/projects.yaml
|
|
1133
|
-
projects:
|
|
1134
|
-
myproject:
|
|
1135
|
-
name: "My Project"
|
|
1136
|
-
path: /home/user/projects/myproject
|
|
1137
|
-
linear_team: PRJ
|
|
1138
|
-
|
|
1139
|
-
workspace:
|
|
1140
|
-
type: polyrepo # or monorepo
|
|
1141
|
-
workspaces_dir: workspaces
|
|
1142
|
-
|
|
1143
|
-
docker:
|
|
1144
|
-
traefik: infra/docker-compose.traefik.yml
|
|
1145
|
-
compose_template: infra/.devcontainer-template
|
|
1146
|
-
|
|
1147
|
-
database:
|
|
1148
|
-
seed_file: /home/user/projects/myproject/infra/seed/seed.sql
|
|
1149
|
-
container_name: "{{PROJECT}}-postgres-1"
|
|
1150
|
-
|
|
1151
|
-
agent:
|
|
1152
|
-
template_dir: infra/.agent-template
|
|
1153
|
-
templates:
|
|
1154
|
-
- source: CLAUDE.md.template
|
|
1155
|
-
target: CLAUDE.md
|
|
1156
|
-
```
|
|
1157
|
-
|
|
1158
|
-
### Quick Checklist
|
|
1159
|
-
|
|
1160
|
-
| Component | Required? | Location | Purpose |
|
|
1161
|
-
|-----------|-----------|----------|---------|
|
|
1162
|
-
| Docker Compose template | Yes (for Docker workspaces) | `infra/.devcontainer-template/` | Container configuration |
|
|
1163
|
-
| Traefik config | Only for HTTPS | `infra/docker-compose.traefik.yml` | Reverse proxy |
|
|
1164
|
-
| Seed file | Only if database needed | `infra/seed/seed.sql` | Pre-populate database |
|
|
1165
|
-
| Agent template | Recommended | `infra/.agent-template/` | AI instructions |
|
|
1166
|
-
| Project skills | Optional | `.claude/skills/` | Project-specific workflows |
|
|
1167
|
-
|
|
1168
|
-
### Example: Minimal Setup
|
|
1169
|
-
|
|
1170
|
-
For a simple monorepo with no Docker:
|
|
1171
|
-
|
|
1172
|
-
```yaml
|
|
1173
|
-
# ~/.panopticon/projects.yaml
|
|
1174
|
-
projects:
|
|
1175
|
-
simple-app:
|
|
1176
|
-
name: "Simple App"
|
|
1177
|
-
path: /home/user/projects/simple-app
|
|
1178
|
-
linear_team: APP
|
|
1179
|
-
# No workspace config needed - uses git worktrees
|
|
1180
|
-
```
|
|
329
|
+
## 🤝 Contributing
|
|
1181
330
|
|
|
1182
|
-
|
|
331
|
+
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
|
1183
332
|
|
|
1184
333
|
---
|
|
1185
334
|
|
|
1186
|
-
##
|
|
1187
|
-
|
|
1188
|
-
For projects with multiple git repositories (like separate frontend/backend repos), configure workspace settings directly in `projects.yaml`.
|
|
1189
|
-
|
|
1190
|
-
### Recommended: Separate Infra Repository
|
|
1191
|
-
|
|
1192
|
-
For polyrepo projects, we strongly recommend maintaining a **dedicated infrastructure repository** alongside your code repos:
|
|
1193
|
-
|
|
1194
|
-
```
|
|
1195
|
-
myproject/
|
|
1196
|
-
├── infra/ # Infrastructure repo (git)
|
|
1197
|
-
│ ├── .devcontainer-template/ # Templates for workspace creation
|
|
1198
|
-
│ │ ├── dev.template # Dev script template
|
|
1199
|
-
│ │ ├── compose.infra.yml.template
|
|
1200
|
-
│ │ └── docker-compose.devcontainer.yml.template
|
|
1201
|
-
│ ├── new-feature # Script to create workspaces
|
|
1202
|
-
│ ├── remove-feature # Script to clean up workspaces
|
|
1203
|
-
│ ├── certs/ # SSL certificates
|
|
1204
|
-
│ └── traefik/ # Traefik config
|
|
1205
|
-
├── frontend/ # Frontend repo (git)
|
|
1206
|
-
├── backend/ # Backend repo (git)
|
|
1207
|
-
└── workspaces/ # Feature workspaces (git worktrees)
|
|
1208
|
-
└── feature-xxx/
|
|
1209
|
-
├── fe/ # Worktree of frontend
|
|
1210
|
-
├── api/ # Worktree of backend
|
|
1211
|
-
└── .devcontainer/ # Generated from templates
|
|
1212
|
-
```
|
|
1213
|
-
|
|
1214
|
-
**Benefits of a separate infra repo:**
|
|
1215
|
-
|
|
1216
|
-
1. **Version-controlled templates** - Dev script changes are tracked and shared
|
|
1217
|
-
2. **Centralized configuration** - DNS, ports, Traefik rules in one place
|
|
1218
|
-
3. **Workspace consistency** - All workspaces use the same templates
|
|
1219
|
-
4. **Team collaboration** - Infra changes go through normal PR review
|
|
1220
|
-
5. **Easy updates** - Fix a template once, regenerate affected workspaces
|
|
1221
|
-
|
|
1222
|
-
**Key files in the infra repo:**
|
|
1223
|
-
|
|
1224
|
-
| File | Purpose |
|
|
1225
|
-
|------|---------|
|
|
1226
|
-
| `dev.template` | Template for `./dev` script (container management) |
|
|
1227
|
-
| `new-feature` | Creates workspace with git worktrees + devcontainer |
|
|
1228
|
-
| `remove-feature` | Cleans up workspace and worktrees |
|
|
1229
|
-
| `.devcontainer-template/` | Docker Compose and devcontainer templates |
|
|
1230
|
-
|
|
1231
|
-
|
|
1232
|
-
|
|
1233
|
-
```yaml
|
|
1234
|
-
projects:
|
|
1235
|
-
myapp:
|
|
1236
|
-
name: "My App"
|
|
1237
|
-
path: /home/user/projects/myapp
|
|
1238
|
-
linear_team: APP
|
|
1239
|
-
|
|
1240
|
-
workspace:
|
|
1241
|
-
type: polyrepo
|
|
1242
|
-
workspaces_dir: workspaces
|
|
1243
|
-
# Default branch for all repos (optional, defaults to 'main')
|
|
1244
|
-
default_branch: main
|
|
1245
|
-
|
|
1246
|
-
# Git repositories to include in each workspace
|
|
1247
|
-
# Each repo is a SEPARATE git repository with its own .git
|
|
1248
|
-
repos:
|
|
1249
|
-
- name: fe
|
|
1250
|
-
path: frontend # Relative to project root
|
|
1251
|
-
branch_prefix: "feature/"
|
|
1252
|
-
# default_branch: main # Can override workspace default per-repo
|
|
1253
|
-
- name: api
|
|
1254
|
-
path: backend
|
|
1255
|
-
branch_prefix: "feature/"
|
|
1256
|
-
# default_branch: develop # Example: API uses 'develop' as default
|
|
1257
|
-
|
|
1258
|
-
# DNS entries for local development
|
|
1259
|
-
dns:
|
|
1260
|
-
domain: myapp.test
|
|
1261
|
-
entries:
|
|
1262
|
-
- "{{FEATURE_FOLDER}}.{{DOMAIN}}"
|
|
1263
|
-
- "api-{{FEATURE_FOLDER}}.{{DOMAIN}}"
|
|
1264
|
-
sync_method: wsl2hosts # or: hosts_file, dnsmasq
|
|
1265
|
-
|
|
1266
|
-
# Port assignments for services
|
|
1267
|
-
ports:
|
|
1268
|
-
redis:
|
|
1269
|
-
range: [6380, 6499]
|
|
1270
|
-
|
|
1271
|
-
# Service definitions - how to start each service
|
|
1272
|
-
services:
|
|
1273
|
-
- name: api
|
|
1274
|
-
path: api
|
|
1275
|
-
start_command: ./mvnw spring-boot:run
|
|
1276
|
-
docker_command: ./mvnw spring-boot:run
|
|
1277
|
-
health_url: "https://api-{{FEATURE_FOLDER}}.{{DOMAIN}}/actuator/health"
|
|
1278
|
-
port: 8080
|
|
1279
|
-
- name: frontend
|
|
1280
|
-
path: fe
|
|
1281
|
-
start_command: pnpm start
|
|
1282
|
-
docker_command: pnpm start
|
|
1283
|
-
health_url: "https://{{FEATURE_FOLDER}}.{{DOMAIN}}"
|
|
1284
|
-
port: 3000
|
|
1285
|
-
|
|
1286
|
-
# Docker configuration
|
|
1287
|
-
docker:
|
|
1288
|
-
traefik: infra/docker-compose.traefik.yml
|
|
1289
|
-
compose_template: infra/.devcontainer-template
|
|
1290
|
-
|
|
1291
|
-
# Agent configuration templates
|
|
1292
|
-
agent:
|
|
1293
|
-
template_dir: infra/.agent-template
|
|
1294
|
-
templates:
|
|
1295
|
-
- source: CLAUDE.md.template
|
|
1296
|
-
target: CLAUDE.md
|
|
1297
|
-
symlinks:
|
|
1298
|
-
- .claude/commands
|
|
1299
|
-
- .claude/skills
|
|
1300
|
-
|
|
1301
|
-
# Environment template
|
|
1302
|
-
env:
|
|
1303
|
-
template: |
|
|
1304
|
-
COMPOSE_PROJECT_NAME={{COMPOSE_PROJECT}}
|
|
1305
|
-
FRONTEND_URL=https://{{FEATURE_FOLDER}}.{{DOMAIN}}
|
|
1306
|
-
```
|
|
1307
|
-
|
|
1308
|
-
**Template Placeholders:**
|
|
1309
|
-
|
|
1310
|
-
| Placeholder | Example | Description |
|
|
1311
|
-
|------------|---------|-------------|
|
|
1312
|
-
| `{{FEATURE_NAME}}` | `min-123` | Normalized issue ID |
|
|
1313
|
-
| `{{FEATURE_FOLDER}}` | `feature-min-123` | Workspace folder name |
|
|
1314
|
-
| `{{BRANCH_NAME}}` | `feature/min-123` | Git branch name |
|
|
1315
|
-
| `{{COMPOSE_PROJECT}}` | `myapp-feature-min-123` | Docker Compose project |
|
|
1316
|
-
| `{{DOMAIN}}` | `myapp.test` | DNS domain |
|
|
1317
|
-
|
|
1318
|
-
**Service Templates:**
|
|
1319
|
-
|
|
1320
|
-
Panopticon provides built-in templates for common frameworks. Use these to avoid boilerplate:
|
|
1321
|
-
|
|
1322
|
-
| Template | Start Command | Port |
|
|
1323
|
-
|----------|--------------|------|
|
|
1324
|
-
| `react` | `npm start` | 3000 |
|
|
1325
|
-
| `react-vite` | `npm run dev` | 5173 |
|
|
1326
|
-
| `react-pnpm` | `pnpm start` | 3000 |
|
|
1327
|
-
| `nextjs` | `npm run dev` | 3000 |
|
|
1328
|
-
| `spring-boot-maven` | `./mvnw spring-boot:run` | 8080 |
|
|
1329
|
-
| `spring-boot-gradle` | `./gradlew bootRun` | 8080 |
|
|
1330
|
-
| `express` | `npm start` | 3000 |
|
|
1331
|
-
| `fastapi` | `uvicorn main:app --reload` | 8000 |
|
|
1332
|
-
| `django` | `python manage.py runserver` | 8000 |
|
|
1333
|
-
|
|
1334
|
-
Use a template by referencing it in your service config:
|
|
1335
|
-
|
|
1336
|
-
```yaml
|
|
1337
|
-
services:
|
|
1338
|
-
- name: api
|
|
1339
|
-
template: spring-boot-maven
|
|
1340
|
-
path: api
|
|
1341
|
-
health_url: "https://api-{{FEATURE_FOLDER}}.myapp.test/health"
|
|
1342
|
-
```
|
|
1343
|
-
|
|
1344
|
-
See `/pan-workspace-config` skill for complete documentation.
|
|
1345
|
-
|
|
1346
|
-
### Polyrepo Merge Considerations
|
|
1347
|
-
|
|
1348
|
-
> **⚠️ Important:** Polyrepo merging requires special handling. The current merge-agent is optimized for monorepos.
|
|
1349
|
-
|
|
1350
|
-
For polyrepo projects:
|
|
1351
|
-
|
|
1352
|
-
| Feature | Status | Notes |
|
|
1353
|
-
|---------|--------|-------|
|
|
1354
|
-
| Workspace creation | ✅ Supported | Creates worktrees in each repo |
|
|
1355
|
-
| Branch management | ✅ Supported | Each repo gets its own feature branch |
|
|
1356
|
-
| Agent work | ✅ Supported | Agents can work across repos |
|
|
1357
|
-
| Merge | ⚠️ Manual | Push each repo's branch, merge via GitLab/GitHub |
|
|
1358
|
-
|
|
1359
|
-
**Current workflow for polyrepo merges:**
|
|
1360
|
-
|
|
1361
|
-
1. Agent completes work and pushes branches to each repo
|
|
1362
|
-
2. Create merge requests for each repo manually (or via `gh pr create`)
|
|
1363
|
-
3. Review and merge each MR separately
|
|
1364
|
-
4. The "Approve & Merge" button is not yet polyrepo-aware
|
|
1365
|
-
|
|
1366
|
-
**Future enhancement:** Polyrepo-aware merge-agent that handles multiple repos automatically.
|
|
1367
|
-
|
|
1368
|
-
### Managing Projects
|
|
1369
|
-
|
|
1370
|
-
```bash
|
|
1371
|
-
# List registered projects
|
|
1372
|
-
pan project list
|
|
1373
|
-
|
|
1374
|
-
# Add a project
|
|
1375
|
-
pan project add /path/to/project --name myproject --linear-team PRJ
|
|
1376
|
-
|
|
1377
|
-
# Remove a project
|
|
1378
|
-
pan project remove myproject
|
|
1379
|
-
```
|
|
1380
|
-
|
|
1381
|
-
### Database Seeding
|
|
1382
|
-
|
|
1383
|
-
Many projects need a pre-populated database for development and testing. Panopticon provides database seeding commands that work with your existing infrastructure.
|
|
1384
|
-
|
|
1385
|
-
**Problem:** Development databases often need:
|
|
1386
|
-
- Schema with 100+ migrations already applied
|
|
1387
|
-
- Seed data for testing (users, reference data)
|
|
1388
|
-
- External QA database connections
|
|
1389
|
-
- Database snapshots from staging/production (sanitized)
|
|
335
|
+
## ⭐ Star History
|
|
1390
336
|
|
|
1391
|
-
|
|
337
|
+
[](https://star-history.com/#eltmon/panopticon-cli&Date)
|
|
1392
338
|
|
|
1393
|
-
|
|
1394
|
-
projects:
|
|
1395
|
-
myapp:
|
|
1396
|
-
workspace:
|
|
1397
|
-
database:
|
|
1398
|
-
# Path to seed file (loaded on first container start)
|
|
1399
|
-
seed_file: /path/to/sanitized-seed.sql
|
|
339
|
+
---
|
|
1400
340
|
|
|
1401
|
-
|
|
1402
|
-
snapshot_command: "kubectl exec -n prod pod/postgres -- pg_dump -U app mydb"
|
|
341
|
+
## ⚖️ License
|
|
1403
342
|
|
|
1404
|
-
|
|
1405
|
-
external_db:
|
|
1406
|
-
host: qa-db.example.com
|
|
1407
|
-
database: myapp_qa
|
|
1408
|
-
user: readonly
|
|
1409
|
-
password_env: QA_DB_PASSWORD
|
|
343
|
+
MIT License - see [LICENSE](LICENSE) for details.
|
|
1410
344
|
|
|
1411
|
-
|
|
1412
|
-
container_name: "{{PROJECT}}-postgres-1"
|
|
345
|
+
---
|
|
1413
346
|
|
|
1414
|
-
|
|
1415
|
-
|
|
1416
|
-
|
|
1417
|
-
|
|
1418
|
-
```
|
|
1419
|
-
|
|
1420
|
-
**Commands:**
|
|
1421
|
-
|
|
1422
|
-
```bash
|
|
1423
|
-
# Create a snapshot from production/staging
|
|
1424
|
-
pan db snapshot --project myapp --output /path/to/seed.sql
|
|
1425
|
-
|
|
1426
|
-
# Seed a workspace database
|
|
1427
|
-
pan db seed MIN-123
|
|
1428
|
-
|
|
1429
|
-
# Check database status
|
|
1430
|
-
pan db status MIN-123
|
|
1431
|
-
|
|
1432
|
-
# Clean kubectl noise from pg_dump files
|
|
1433
|
-
pan db clean /path/to/dump.sql
|
|
1434
|
-
|
|
1435
|
-
# View database configuration
|
|
1436
|
-
pan db config myapp
|
|
1437
|
-
```
|
|
1438
|
-
|
|
1439
|
-
**Workflow for capturing production data:**
|
|
1440
|
-
|
|
1441
|
-
1. **Create snapshot** from production (via kubectl or direct connection):
|
|
1442
|
-
```bash
|
|
1443
|
-
pan db snapshot --project myapp --sanitize
|
|
1444
|
-
```
|
|
1445
|
-
|
|
1446
|
-
2. **Verify** the seed file:
|
|
1447
|
-
```bash
|
|
1448
|
-
pan db clean /path/to/seed.sql --dry-run
|
|
1449
|
-
```
|
|
1450
|
-
|
|
1451
|
-
3. **Update projects.yaml** with seed file path
|
|
1452
|
-
|
|
1453
|
-
4. **Workspaces** automatically seed on first postgres container start
|
|
1454
|
-
|
|
1455
|
-
**Container integration:**
|
|
1456
|
-
|
|
1457
|
-
Your Docker Compose template should mount the seed directory:
|
|
1458
|
-
|
|
1459
|
-
```yaml
|
|
1460
|
-
# compose.infra.yml
|
|
1461
|
-
services:
|
|
1462
|
-
postgres:
|
|
1463
|
-
image: postgres:16
|
|
1464
|
-
volumes:
|
|
1465
|
-
- pgdata:/var/lib/postgresql/data
|
|
1466
|
-
# Seed database on first startup
|
|
1467
|
-
- /path/to/project/infra/seed:/docker-entrypoint-initdb.d:ro
|
|
1468
|
-
```
|
|
1469
|
-
|
|
1470
|
-
**Troubleshooting:**
|
|
1471
|
-
|
|
1472
|
-
| Issue | Solution |
|
|
1473
|
-
|-------|----------|
|
|
1474
|
-
| "relation does not exist" | Seed file missing or incomplete - run `pan db snapshot` |
|
|
1475
|
-
| Slow database startup | Large seed file - consider pruning old data |
|
|
1476
|
-
| kubectl garbage in dump | Run `pan db clean <file>` to remove stderr noise |
|
|
1477
|
-
| Migrations fail after seed | Check Flyway version matches seed file's schema_history |
|
|
1478
|
-
|
|
1479
|
-
### Agent Completion Notifications
|
|
1480
|
-
|
|
1481
|
-
Panopticon includes a notification system that alerts you when agents complete their work.
|
|
1482
|
-
|
|
1483
|
-
**Desktop Notifications:**
|
|
1484
|
-
|
|
1485
|
-
The `notify-complete` script sends desktop notifications across platforms:
|
|
1486
|
-
|
|
1487
|
-
| Platform | Notification Method |
|
|
1488
|
-
|----------|---------------------|
|
|
1489
|
-
| WSL2/Windows | PowerShell toast notifications |
|
|
1490
|
-
| macOS | osascript display notification |
|
|
1491
|
-
| Linux | notify-send |
|
|
1492
|
-
|
|
1493
|
-
**Usage:**
|
|
1494
|
-
```bash
|
|
1495
|
-
# Send a completion notification
|
|
1496
|
-
~/.panopticon/bin/notify-complete MIN-123 "Fixed login button" "https://gitlab.com/mr/456"
|
|
1497
|
-
```
|
|
1498
|
-
|
|
1499
|
-
**Completion log:** All notifications are logged to `~/.panopticon/agent-completed.log` with timestamps.
|
|
1500
|
-
|
|
1501
|
-
**Integration with agent workflows:**
|
|
1502
|
-
|
|
1503
|
-
Agents can call `notify-complete` at the end of their work:
|
|
1504
|
-
```bash
|
|
1505
|
-
# In agent completion script or /work-complete skill
|
|
1506
|
-
notify-complete "$ISSUE_ID" "$SUMMARY" "$MR_URL"
|
|
1507
|
-
```
|
|
1508
|
-
|
|
1509
|
-
---
|
|
1510
|
-
|
|
1511
|
-
## Commands
|
|
1512
|
-
|
|
1513
|
-
### Core Commands
|
|
1514
|
-
|
|
1515
|
-
```bash
|
|
1516
|
-
pan init # Initialize ~/.panopticon/
|
|
1517
|
-
pan sync # Sync skills, commands, agents, AND hooks to all AI tools
|
|
1518
|
-
pan sync --dry-run # Preview what will be synced
|
|
1519
|
-
pan doctor # Check system health
|
|
1520
|
-
pan skills # List available skills
|
|
1521
|
-
pan status # Show running agents
|
|
1522
|
-
pan up # Start dashboard (Docker or minimal)
|
|
1523
|
-
pan down # Stop dashboard and services
|
|
1524
|
-
pan update # Update Panopticon to latest version
|
|
1525
|
-
pan backup # Create backup of ~/.panopticon/
|
|
1526
|
-
pan restore # Restore from backup
|
|
1527
|
-
pan setup hooks # Install Claude Code hooks (heartbeat, etc.)
|
|
1528
|
-
```
|
|
1529
|
-
|
|
1530
|
-
### Beads Management
|
|
1531
|
-
|
|
1532
|
-
Beads is an optional git-backed issue tracker for persistent task tracking. Panopticon includes commands to manage beads databases and automatic cleanup after merges.
|
|
1533
|
-
|
|
1534
|
-
**Installation:** Beads is automatically installed during `pan install`. You can also install/upgrade manually:
|
|
1535
|
-
|
|
1536
|
-
```bash
|
|
1537
|
-
# Check beads version and available updates
|
|
1538
|
-
pan beads upgrade --check
|
|
1539
|
-
|
|
1540
|
-
# Upgrade to latest version
|
|
1541
|
-
pan beads upgrade
|
|
1542
|
-
|
|
1543
|
-
# Show beads statistics (total, open, closed, old)
|
|
1544
|
-
pan beads stats
|
|
1545
|
-
|
|
1546
|
-
# Compact beads - remove closed issues older than 30 days
|
|
1547
|
-
pan beads compact
|
|
1548
|
-
|
|
1549
|
-
# Customize the threshold (e.g., 60 days)
|
|
1550
|
-
pan beads compact --days 60
|
|
1551
|
-
|
|
1552
|
-
# Preview what would be removed (dry run)
|
|
1553
|
-
pan beads compact --dry-run
|
|
1554
|
-
```
|
|
1555
|
-
|
|
1556
|
-
**Recommended version:** v0.47.1+ includes important fixes for git worktree isolation.
|
|
1557
|
-
|
|
1558
|
-
**Workspace Isolation:**
|
|
1559
|
-
|
|
1560
|
-
With beads v0.47.1+, workspaces share the same database but use labels for isolation:
|
|
1561
|
-
|
|
1562
|
-
```bash
|
|
1563
|
-
# In workspace for PAN-83, list only that workspace's tasks
|
|
1564
|
-
bd list --label workspace:pan-83
|
|
1565
|
-
|
|
1566
|
-
# Or use bd ready with label filter
|
|
1567
|
-
bd ready --label workspace:pan-83
|
|
1568
|
-
```
|
|
1569
|
-
|
|
1570
|
-
Panopticon automatically creates beads with `workspace:<issue-id>` labels when you create a workspace. Agents can filter to see only their workspace's tasks.
|
|
1571
|
-
|
|
1572
|
-
**Automatic Compaction:**
|
|
1573
|
-
|
|
1574
|
-
After every successful merge, the merge-agent automatically:
|
|
1575
|
-
1. Checks for closed beads older than 30 days
|
|
1576
|
-
2. If found, runs `bd admin compact --days 30`
|
|
1577
|
-
3. Commits the compacted beads
|
|
1578
|
-
4. Pushes to remote
|
|
1579
|
-
|
|
1580
|
-
This keeps the beads database clean without manual intervention.
|
|
1581
|
-
|
|
1582
|
-
**Why compact beads?**
|
|
1583
|
-
|
|
1584
|
-
Beads are committed to git for collaborative planning (see "Git-Backed Collaborative Planning" section). Over time, closed issues accumulate. Compaction removes old closed issues while preserving:
|
|
1585
|
-
- Open issues (always kept)
|
|
1586
|
-
- Recently closed issues (< 30 days by default)
|
|
1587
|
-
- All issue history in git commits
|
|
1588
|
-
|
|
1589
|
-
#### What `pan sync` Does
|
|
1590
|
-
|
|
1591
|
-
`pan sync` synchronizes Panopticon assets to all supported AI tools:
|
|
1592
|
-
|
|
1593
|
-
| Asset Type | Source | Destinations |
|
|
1594
|
-
|------------|--------|--------------|
|
|
1595
|
-
| **Skills** | `~/.panopticon/skills/` | `~/.claude/skills/`, `~/.codex/skills/`, `~/.gemini/skills/` |
|
|
1596
|
-
| **Agents** | `~/.panopticon/agents/*.md` | `~/.claude/agents/` |
|
|
1597
|
-
| **Commands** | `~/.panopticon/commands/` | `~/.claude/commands/` |
|
|
1598
|
-
| **Hooks** | `src/hooks/` (in package) | `~/.panopticon/bin/` |
|
|
1599
|
-
|
|
1600
|
-
**Automatic sync:** Hooks are also synced automatically when you install or upgrade Panopticon via npm (`postinstall` hook).
|
|
1601
|
-
|
|
1602
|
-
### Agent Management
|
|
1603
|
-
|
|
1604
|
-
```bash
|
|
1605
|
-
# Spawn an agent for a Linear issue
|
|
1606
|
-
pan work issue MIN-123
|
|
1607
|
-
|
|
1608
|
-
# List all running agents
|
|
1609
|
-
pan work status
|
|
1610
|
-
|
|
1611
|
-
# Send a message to an agent (handles Enter key automatically)
|
|
1612
|
-
pan work tell min-123 "Please also add tests"
|
|
1613
|
-
|
|
1614
|
-
# Kill an agent
|
|
1615
|
-
pan work kill min-123
|
|
1616
|
-
|
|
1617
|
-
# Show work completed and awaiting review
|
|
1618
|
-
pan work pending
|
|
1619
|
-
|
|
1620
|
-
# Approve agent work, merge MR, update Linear
|
|
1621
|
-
pan work approve min-123
|
|
1622
|
-
|
|
1623
|
-
# List issues from configured trackers
|
|
1624
|
-
pan work list
|
|
1625
|
-
|
|
1626
|
-
# Triage issues from secondary tracker
|
|
1627
|
-
pan work triage
|
|
1628
|
-
|
|
1629
|
-
# Reopen a closed issue and re-run planning
|
|
1630
|
-
pan work reopen min-123
|
|
1631
|
-
|
|
1632
|
-
# Request re-review after fixing feedback (for agents, max 3 auto-requeues)
|
|
1633
|
-
pan work request-review min-123 -m "Fixed: added tests and removed duplication"
|
|
1634
|
-
|
|
1635
|
-
# Deep wipe: completely reset all state for an issue
|
|
1636
|
-
pan work wipe min-123 # Cleans up agents, state, Linear status
|
|
1637
|
-
pan work wipe min-123 -w # Also delete workspace
|
|
1638
|
-
pan work wipe min-123 -y -w # Skip confirmation
|
|
1639
|
-
|
|
1640
|
-
# Recover crashed agents
|
|
1641
|
-
pan work recover min-123
|
|
1642
|
-
pan work recover --all
|
|
1643
|
-
```
|
|
1644
|
-
|
|
1645
|
-
### Convoys: Multi-Agent Orchestration
|
|
1646
|
-
|
|
1647
|
-
Convoys enable Panopticon to run multiple AI agents in parallel for complex tasks like code review. Instead of a single agent doing everything, specialized agents focus on specific concerns and a synthesis agent combines their findings.
|
|
1648
|
-
|
|
1649
|
-
**Why Convoys?**
|
|
1650
|
-
|
|
1651
|
-
When reviewing code, a single AI agent must context-switch between:
|
|
1652
|
-
- Checking for logic errors
|
|
1653
|
-
- Looking for security vulnerabilities
|
|
1654
|
-
- Analyzing performance issues
|
|
1655
|
-
|
|
1656
|
-
This leads to:
|
|
1657
|
-
- Shallow reviews (can't go deep on everything)
|
|
1658
|
-
- Missed issues (focus on one area, miss others)
|
|
1659
|
-
- Long sequential execution (can't parallelize)
|
|
1660
|
-
|
|
1661
|
-
Convoys solve this by **specialization + parallelization**:
|
|
1662
|
-
- 3 focused agents review in parallel (10x faster)
|
|
1663
|
-
- Each agent goes deep in their domain
|
|
1664
|
-
- Synthesis agent combines findings with prioritization
|
|
1665
|
-
|
|
1666
|
-
#### Built-in Convoy Templates
|
|
1667
|
-
|
|
1668
|
-
| Template | Agents | Use Case |
|
|
1669
|
-
|----------|--------|----------|
|
|
1670
|
-
| `code-review` | correctness, security, performance, synthesis | Comprehensive code review |
|
|
1671
|
-
| `planning` | planner | Codebase exploration and planning |
|
|
1672
|
-
| `triage` | (dynamic) | Parallel issue triage |
|
|
1673
|
-
| `health-monitor` | monitor | Check health of running agents |
|
|
1674
|
-
|
|
1675
|
-
#### Quick Start
|
|
1676
|
-
|
|
1677
|
-
```bash
|
|
1678
|
-
# Run a parallel code review
|
|
1679
|
-
pan convoy start code-review --files "src/**/*.ts"
|
|
1680
|
-
|
|
1681
|
-
# Check status
|
|
1682
|
-
pan convoy status
|
|
1683
|
-
|
|
1684
|
-
# List all convoys (running and completed)
|
|
1685
|
-
pan convoy list
|
|
1686
|
-
|
|
1687
|
-
# Stop a convoy
|
|
1688
|
-
pan convoy stop <convoy-id>
|
|
1689
|
-
```
|
|
1690
|
-
|
|
1691
|
-
#### How Code Review Convoy Works
|
|
1692
|
-
|
|
1693
|
-
```
|
|
1694
|
-
pan convoy start code-review --files "src/**/*.ts"
|
|
1695
|
-
│
|
|
1696
|
-
├─→ Phase 1 (Parallel): 3 specialized reviewers run simultaneously
|
|
1697
|
-
│ ├─→ Correctness (Haiku) → correctness.md
|
|
1698
|
-
│ ├─→ Security (Sonnet) → security.md
|
|
1699
|
-
│ └─→ Performance (Haiku) → performance.md
|
|
1700
|
-
│
|
|
1701
|
-
└─→ Phase 2 (Sequential): Synthesis agent runs after Phase 1 completes
|
|
1702
|
-
└─→ Synthesis reads all 3 reviews → synthesis.md
|
|
1703
|
-
```
|
|
1704
|
-
|
|
1705
|
-
**Phase 1 - Specialized Reviews (Parallel)**
|
|
1706
|
-
- **Correctness** (Haiku) - Logic errors, edge cases, type safety
|
|
1707
|
-
- **Security** (Sonnet) - OWASP Top 10, injection, XSS, auth issues
|
|
1708
|
-
- **Performance** (Haiku) - N+1 queries, blocking ops, memory leaks
|
|
1709
|
-
|
|
1710
|
-
**Phase 2 - Synthesis (Sequential)**
|
|
1711
|
-
- Reads all three review files
|
|
1712
|
-
- Removes duplicates (same issue found by multiple reviewers)
|
|
1713
|
-
- Prioritizes findings (blocker → critical → high → medium → low)
|
|
1714
|
-
- Generates unified report with action items
|
|
1715
|
-
|
|
1716
|
-
#### What is Synthesis?
|
|
1717
|
-
|
|
1718
|
-
Synthesis is the process of combining findings from multiple parallel agents into a single, prioritized, actionable report.
|
|
1719
|
-
|
|
1720
|
-
**Without synthesis**, after 3 parallel reviews you get:
|
|
1721
|
-
- 3 separate markdown files to read
|
|
1722
|
-
- Duplicate findings (same issue reported differently)
|
|
1723
|
-
- No prioritization (which to fix first?)
|
|
1724
|
-
- Mental overhead to merge them yourself
|
|
1725
|
-
|
|
1726
|
-
**With synthesis**, you get:
|
|
1727
|
-
- Single unified report
|
|
1728
|
-
- Deduplicated findings
|
|
1729
|
-
- AI-prioritized by severity × impact
|
|
1730
|
-
- Clear action items
|
|
1731
|
-
|
|
1732
|
-
**Example synthesis output:**
|
|
1733
|
-
|
|
1734
|
-
```markdown
|
|
1735
|
-
# Code Review - Complete Analysis
|
|
1736
|
-
|
|
1737
|
-
## Executive Summary
|
|
1738
|
-
- 2 blockers (MUST FIX)
|
|
1739
|
-
- 3 critical issues
|
|
1740
|
-
- 5 high-priority items
|
|
1741
|
-
|
|
1742
|
-
## Top Priority
|
|
1743
|
-
1. SQL injection in auth.ts:42 (Security, Critical)
|
|
1744
|
-
2. execSync blocking event loop in sync.ts:89 (Performance, Blocker)
|
|
1745
|
-
3. Null pointer in user fetch in api.ts:156 (Correctness, High)
|
|
1746
|
-
|
|
1747
|
-
## Blocker Issues
|
|
1748
|
-
[Detailed findings with code examples and fixes]
|
|
1749
|
-
|
|
1750
|
-
## Critical Issues
|
|
1751
|
-
[...]
|
|
1752
|
-
|
|
1753
|
-
## Review Statistics
|
|
1754
|
-
- Files reviewed: 12
|
|
1755
|
-
- Issues found: 10
|
|
1756
|
-
- Duplicates removed: 3
|
|
1757
|
-
```
|
|
1758
|
-
|
|
1759
|
-
#### Convoy Commands
|
|
1760
|
-
|
|
1761
|
-
```bash
|
|
1762
|
-
# Start a convoy
|
|
1763
|
-
pan convoy start <template> [options]
|
|
1764
|
-
--files <pattern> # File pattern (e.g., "src/**/*.ts")
|
|
1765
|
-
--pr-url <url> # Pull request URL
|
|
1766
|
-
--issue-id <id> # Issue ID
|
|
1767
|
-
--project-path <path> # Project path (defaults to cwd)
|
|
1768
|
-
|
|
1769
|
-
# Check convoy status
|
|
1770
|
-
pan convoy status [convoy-id] # Show status (defaults to most recent)
|
|
1771
|
-
|
|
1772
|
-
# List convoys
|
|
1773
|
-
pan convoy list # All convoys
|
|
1774
|
-
pan convoy list --status running # Filter by status
|
|
1775
|
-
|
|
1776
|
-
# Stop a convoy
|
|
1777
|
-
pan convoy stop <convoy-id> # Kill all agents, mark failed
|
|
1778
|
-
```
|
|
1779
|
-
|
|
1780
|
-
#### Custom Convoy Templates
|
|
1781
|
-
|
|
1782
|
-
Create custom templates in `~/.panopticon/convoy-templates/`:
|
|
1783
|
-
|
|
1784
|
-
```json
|
|
1785
|
-
{
|
|
1786
|
-
"name": "lightweight-review",
|
|
1787
|
-
"description": "Quick security-only review",
|
|
1788
|
-
"agents": [
|
|
1789
|
-
{
|
|
1790
|
-
"role": "security",
|
|
1791
|
-
"subagent": "code-review-security",
|
|
1792
|
-
"parallel": false
|
|
1793
|
-
}
|
|
1794
|
-
],
|
|
1795
|
-
"config": {
|
|
1796
|
-
"outputDir": ".claude/reviews",
|
|
1797
|
-
"timeout": 600000
|
|
1798
|
-
}
|
|
1799
|
-
}
|
|
1800
|
-
```
|
|
1801
|
-
|
|
1802
|
-
Then use with: `pan convoy start lightweight-review --files "src/**/*.ts"`
|
|
1803
|
-
|
|
1804
|
-
### Health Monitoring
|
|
1805
|
-
|
|
1806
|
-
```bash
|
|
1807
|
-
# Run a health check
|
|
1808
|
-
pan work health check
|
|
1809
|
-
|
|
1810
|
-
# Show health status of all agents
|
|
1811
|
-
pan work health status
|
|
1812
|
-
|
|
1813
|
-
# Start the health daemon (background monitoring)
|
|
1814
|
-
pan work health daemon --interval 30
|
|
1815
|
-
```
|
|
1816
|
-
|
|
1817
|
-
### Test Runner
|
|
1818
|
-
|
|
1819
|
-
```bash
|
|
1820
|
-
# Run all tests for a workspace
|
|
1821
|
-
pan test run min-123
|
|
1822
|
-
|
|
1823
|
-
# Run tests for main branch
|
|
1824
|
-
pan test run main
|
|
1825
|
-
|
|
1826
|
-
# Run specific test suites only
|
|
1827
|
-
pan test run min-123 --tests backend,frontend_unit
|
|
1828
|
-
|
|
1829
|
-
# List configured tests for a project
|
|
1830
|
-
pan test list
|
|
1831
|
-
|
|
1832
|
-
# List tests for specific project
|
|
1833
|
-
pan test list myproject
|
|
1834
|
-
```
|
|
1835
|
-
|
|
1836
|
-
**Test Configuration:**
|
|
1837
|
-
|
|
1838
|
-
Configure test suites in `projects.yaml`:
|
|
1839
|
-
|
|
1840
|
-
```yaml
|
|
1841
|
-
projects:
|
|
1842
|
-
myapp:
|
|
1843
|
-
tests:
|
|
1844
|
-
backend:
|
|
1845
|
-
type: maven # maven, vitest, jest, playwright, pytest, cargo
|
|
1846
|
-
path: api # Path relative to workspace
|
|
1847
|
-
command: ./mvnw test # Command to run
|
|
1848
|
-
|
|
1849
|
-
frontend_unit:
|
|
1850
|
-
type: vitest
|
|
1851
|
-
path: fe
|
|
1852
|
-
command: pnpm test:unit --run
|
|
1853
|
-
container: true # Run inside Docker container
|
|
1854
|
-
container_name: "{{COMPOSE_PROJECT}}-fe-1"
|
|
1855
|
-
|
|
1856
|
-
frontend_e2e:
|
|
1857
|
-
type: playwright
|
|
1858
|
-
path: fe
|
|
1859
|
-
command: pnpm test:e2e
|
|
1860
|
-
env:
|
|
1861
|
-
BASE_URL: "https://{{FEATURE_FOLDER}}.myapp.test"
|
|
1862
|
-
```
|
|
1863
|
-
|
|
1864
|
-
**Reports:**
|
|
1865
|
-
|
|
1866
|
-
Test results are saved to `{project}/reports/test-run-{target}-{timestamp}.md` with detailed logs for each suite.
|
|
1867
|
-
|
|
1868
|
-
**Notifications:**
|
|
1869
|
-
|
|
1870
|
-
Desktop notifications are sent when tests complete (disable with `--no-notify`).
|
|
1871
|
-
|
|
1872
|
-
See `/pan-test-config` skill for complete documentation.
|
|
1873
|
-
|
|
1874
|
-
### FPP Hooks (Fixed Point Principle)
|
|
1875
|
-
|
|
1876
|
-
```bash
|
|
1877
|
-
# Check for pending work on hook
|
|
1878
|
-
pan work hook check
|
|
1879
|
-
|
|
1880
|
-
# Push work to an agent's hook
|
|
1881
|
-
pan work hook push agent-min-123 "Continue with tests"
|
|
1882
|
-
|
|
1883
|
-
# Send mail to an agent
|
|
1884
|
-
pan work hook mail agent-min-123 "Review feedback received"
|
|
1885
|
-
```
|
|
1886
|
-
|
|
1887
|
-
### Workspace Management
|
|
1888
|
-
|
|
1889
|
-
**Workspaces are git worktrees** - isolated working directories for each issue/feature. Each workspace:
|
|
1890
|
-
- Has its own feature branch (e.g., `feature/min-123-add-login`)
|
|
1891
|
-
- Shares git history with the main repo (no separate clone)
|
|
1892
|
-
- Can run independently (separate node_modules, builds, etc.)
|
|
1893
|
-
- Is located at `{project}/workspaces/{issue-id}/`
|
|
1894
|
-
|
|
1895
|
-
This allows multiple agents to work on different features simultaneously without conflicts.
|
|
1896
|
-
|
|
1897
|
-
> **IMPORTANT: Main Project Branch Convention**
|
|
1898
|
-
>
|
|
1899
|
-
> The main project directory should **ALWAYS** stay on the `main` branch. All feature work happens in workspaces (git worktrees), never in the main project.
|
|
1900
|
-
>
|
|
1901
|
-
> - **Main project**: Always on `main` - serves as the stable reference point
|
|
1902
|
-
> - **Workspaces**: Each has its own feature branch checked out
|
|
1903
|
-
> - **Want to check something?** Create a worktree, don't checkout in main
|
|
1904
|
-
> - **Quick test?** Create a worktree
|
|
1905
|
-
> - **Emergency hotfix?** Create a worktree
|
|
1906
|
-
>
|
|
1907
|
-
> This convention ensures:
|
|
1908
|
-
> 1. Specialists (review-agent, test-agent) always find the correct code
|
|
1909
|
-
> 2. Merge operations have a clean target
|
|
1910
|
-
> 3. Multiple agents don't interfere with each other
|
|
1911
|
-
>
|
|
1912
|
-
> If you see a warning like "Main project is on branch 'feature/xxx' instead of 'main'", something has incorrectly checked out a feature branch in the main project. Fix it with `git checkout main`.
|
|
1913
|
-
|
|
1914
|
-
#### Git Hooks for Branch Protection
|
|
1915
|
-
|
|
1916
|
-
Panopticon provides git hooks to enforce the main branch convention. These hooks are automatically installed:
|
|
1917
|
-
|
|
1918
|
-
- **On `pan project add`** - Hooks are installed when registering a new project
|
|
1919
|
-
- **On `pan sync`** - Hooks are updated in all registered projects
|
|
1920
|
-
|
|
1921
|
-
The hooks are polyrepo-aware and will install in all git repositories within your project.
|
|
1922
|
-
|
|
1923
|
-
**Auto-revert behavior:**
|
|
1924
|
-
- **Agents & planning sessions**: Automatically revert to `main` if they accidentally checkout a feature branch
|
|
1925
|
-
- **Human users**: Display a prominent warning (no auto-revert by default)
|
|
1926
|
-
|
|
1927
|
-
To enable auto-revert for humans:
|
|
1928
|
-
```bash
|
|
1929
|
-
export PANOPTICON_AUTO_REVERT_CHECKOUT=1 # Add to .bashrc/.zshrc
|
|
1930
|
-
```
|
|
1931
|
-
|
|
1932
|
-
Manual hook installation (for projects not in registry):
|
|
1933
|
-
```bash
|
|
1934
|
-
./scripts/install-git-hooks.sh /path/to/your/project
|
|
1935
|
-
```
|
|
1936
|
-
|
|
1937
|
-
#### Planning vs Work Agent Safeguard
|
|
1938
|
-
|
|
1939
|
-
The dashboard prevents starting a work agent (`agent-<issue>`) while a planning agent (`planning-<issue>`) is still running for the same issue. This prevents conflicts where both agents try to modify the same workspace.
|
|
1940
|
-
|
|
1941
|
-
If you see "Planning agent is still running" when trying to start work:
|
|
1942
|
-
1. **Complete the planning session** - Use "Complete Planning" button
|
|
1943
|
-
2. **Or abort planning** - Use "Abort Planning" if you want to discard
|
|
1944
|
-
3. **Or kill the session manually** - `tmux kill-session -t planning-<issue>`
|
|
1945
|
-
|
|
1946
|
-
#### Specialist Agent Safeguards
|
|
1947
|
-
|
|
1948
|
-
All specialist agents (review-agent, test-agent, merge-agent) are configured to:
|
|
1949
|
-
1. **Run in workspaces only** - Never in the main project directory
|
|
1950
|
-
2. **Never checkout branches** - They work with the branch already in the workspace
|
|
1951
|
-
3. **Create workspaces if needed** - Use `pan workspace create <ISSUE-ID>` instead of `git checkout`
|
|
1952
|
-
|
|
1953
|
-
These safeguards are enforced through:
|
|
1954
|
-
- **Prompt instructions** - Clear warnings in all specialist prompts
|
|
1955
|
-
- **Code enforcement** - Specialists spawn with workspace as cwd
|
|
1956
|
-
- **Git hooks** - Auto-revert if checkout detected in tmux sessions
|
|
1957
|
-
|
|
1958
|
-
#### Git-Backed Collaborative Planning
|
|
1959
|
-
|
|
1960
|
-
| Start Planning | Codebase Exploration | Discovery Questions |
|
|
1961
|
-
|----------------|---------------------|---------------------|
|
|
1962
|
-
|  |  |  |
|
|
1963
|
-
| Click to create workspace and start AI planning | Claude explores the codebase, reads docs, understands patterns | Interactive questions to clarify requirements and approach |
|
|
1964
|
-
|
|
1965
|
-
Planning artifacts are stored **inside the workspace**:
|
|
1966
|
-
|
|
1967
|
-
> ⚠️ **Note: `.planning/` is currently ephemeral (not tracked in git)**
|
|
1968
|
-
>
|
|
1969
|
-
> The `.planning/` directory is listed in `.gitignore` to prevent cross-contamination between issues. When branches merge, planning state from issue A could contaminate issue B's workspace, causing agents to work on the wrong tasks.
|
|
1970
|
-
>
|
|
1971
|
-
> **Current behavior:** Planning state is local to your machine only. If you switch machines, you'll need to re-run the planning session.
|
|
1972
|
-
>
|
|
1973
|
-
> See [#111](https://github.com/eltmon/panopticon-cli/issues/111) for the future enhancement to support cross-machine planning sync safely.
|
|
1974
|
-
|
|
1975
|
-
```
|
|
1976
|
-
workspaces/feature-min-123/
|
|
1977
|
-
├── .planning/ # ⚠️ NOT tracked in git (ephemeral)
|
|
1978
|
-
│ ├── STATE.md # Current planning state
|
|
1979
|
-
│ ├── output.jsonl # Full conversation history
|
|
1980
|
-
│ ├── PLANNING_PROMPT.md # Initial planning prompt
|
|
1981
|
-
│ ├── CONTINUATION_PROMPT.md # Context for continued sessions
|
|
1982
|
-
│ └── output-*.jsonl # Backup of previous rounds
|
|
1983
|
-
└── ... (code)
|
|
1984
|
-
```
|
|
1985
|
-
|
|
1986
|
-

|
|
1987
|
-
|
|
1988
|
-
When the planning session completes, the AI generates:
|
|
1989
|
-
- **STATE.md** - Current understanding, decisions made, and implementation plan
|
|
1990
|
-
- **Beads tasks** - Trackable sub-tasks with dependencies for the implementation
|
|
1991
|
-
- **Feature PRD** - Copied to `docs/prds/active/{issue}-plan.md` for documentation
|
|
1992
|
-
|
|
1993
|
-
**Future capabilities (currently disabled - see note above):**
|
|
1994
|
-
|
|
1995
|
-
1. ~~**Collaborative async planning** - Push your branch, someone else pulls and continues the planning session with full context~~
|
|
1996
|
-
2. ~~**Branch portability** - The planning state travels with the feature branch~~
|
|
1997
|
-
|
|
1998
|
-
**What still works:**
|
|
1999
|
-
|
|
2000
|
-
1. **Context recovery** - If Claude's context compacts, STATE.md and beads preserve the planning decisions
|
|
2001
|
-
2. **Audit trail** - See decisions made in STATE.md
|
|
2002
|
-
3. **Beads tasks** - Sub-tasks created during planning ARE persisted (beads uses label-based isolation)
|
|
2003
|
-
|
|
2004
|
-
```bash
|
|
2005
|
-
# Create a workspace (git worktree) without starting an agent
|
|
2006
|
-
pan workspace create MIN-123
|
|
2007
|
-
|
|
2008
|
-
# Create workspace and start Docker containers
|
|
2009
|
-
pan workspace create MIN-123 --docker
|
|
2010
|
-
|
|
2011
|
-
# List all workspaces
|
|
2012
|
-
pan workspace list
|
|
2013
|
-
|
|
2014
|
-
# Destroy a workspace
|
|
2015
|
-
pan workspace destroy MIN-123
|
|
2016
|
-
|
|
2017
|
-
# Force destroy (even with uncommitted changes)
|
|
2018
|
-
pan workspace destroy MIN-123 --force
|
|
2019
|
-
```
|
|
2020
|
-
|
|
2021
|
-
#### Docker Integration
|
|
2022
|
-
|
|
2023
|
-
The `--docker` flag automatically starts containers after workspace creation:
|
|
2024
|
-
|
|
2025
|
-
```bash
|
|
2026
|
-
pan workspace create MIN-123 --docker
|
|
2027
|
-
```
|
|
2028
|
-
|
|
2029
|
-
**What it does:**
|
|
2030
|
-
1. Creates the workspace (git worktree or custom command)
|
|
2031
|
-
2. Looks for docker-compose files in:
|
|
2032
|
-
- `{workspace}/docker-compose.yml`
|
|
2033
|
-
- `{workspace}/docker-compose.yaml`
|
|
2034
|
-
- `{workspace}/.devcontainer/docker-compose.yml`
|
|
2035
|
-
- `{workspace}/.devcontainer/docker-compose.devcontainer.yml`
|
|
2036
|
-
- `{workspace}/.devcontainer/compose.yml`
|
|
2037
|
-
3. Runs `docker compose -p "{project}-feature-{issue}" -f {file} up -d --build`
|
|
2038
|
-
|
|
2039
|
-
**Docker Project Naming:**
|
|
2040
|
-
|
|
2041
|
-
Each workspace gets a unique Docker Compose project name to avoid container conflicts:
|
|
2042
|
-
- Format: `{project-name}-feature-{issue-id}` (e.g., `mind-your-now-feature-min-123`)
|
|
2043
|
-
- The project name comes from `name` in your `~/.panopticon/projects.yaml`
|
|
2044
|
-
- Container names follow: `{project}-{service}-1` (e.g., `mind-your-now-feature-min-123-api-1`)
|
|
2045
|
-
|
|
2046
|
-
This allows multiple workspaces to run simultaneously without port or name conflicts.
|
|
2047
|
-
|
|
2048
|
-
**Why this matters:**
|
|
2049
|
-
- Containers start warming up while you review the issue
|
|
2050
|
-
- Environment is ready when the planning agent starts asking questions
|
|
2051
|
-
- You can test assumptions during planning without waiting for builds
|
|
2052
|
-
|
|
2053
|
-
**Dashboard integration:**
|
|
2054
|
-
|
|
2055
|
-
The planning dialog includes a "Start Docker containers" checkbox:
|
|
2056
|
-
- **Default:** Enabled (containers start automatically)
|
|
2057
|
-
- **Preference saved:** Your choice is remembered in browser localStorage
|
|
2058
|
-
- **Key:** `panopticon.planning.startDocker`
|
|
2059
|
-
|
|
2060
|
-
To change the default via browser console:
|
|
2061
|
-
```javascript
|
|
2062
|
-
// Disable Docker by default
|
|
2063
|
-
localStorage.setItem('panopticon.planning.startDocker', 'false');
|
|
2064
|
-
|
|
2065
|
-
// Enable Docker by default (this is the out-of-box default)
|
|
2066
|
-
localStorage.setItem('panopticon.planning.startDocker', 'true');
|
|
2067
|
-
```
|
|
2068
|
-
|
|
2069
|
-
**Example workflow:**
|
|
2070
|
-
```bash
|
|
2071
|
-
# From dashboard: click "Start Planning" (Docker enabled by default)
|
|
2072
|
-
# Or from CLI:
|
|
2073
|
-
pan workspace create MIN-123 --docker
|
|
2074
|
-
|
|
2075
|
-
# While containers build in background:
|
|
2076
|
-
# - Review the Linear issue
|
|
2077
|
-
# - Check related PRs
|
|
2078
|
-
# - Think about approach
|
|
2079
|
-
|
|
2080
|
-
# By the time you're ready to engage with the planning agent,
|
|
2081
|
-
# the dev environment is warm and ready for testing
|
|
2082
|
-
```
|
|
2083
|
-
|
|
2084
|
-
### Project Management
|
|
2085
|
-
|
|
2086
|
-
```bash
|
|
2087
|
-
# Register a project
|
|
2088
|
-
pan project add /path/to/project --name myproject
|
|
2089
|
-
|
|
2090
|
-
# List managed projects
|
|
2091
|
-
pan project list
|
|
2092
|
-
|
|
2093
|
-
# Show project details
|
|
2094
|
-
pan project show myproject
|
|
2095
|
-
|
|
2096
|
-
# Initialize project config (creates .panopticon.json)
|
|
2097
|
-
pan project init
|
|
2098
|
-
|
|
2099
|
-
# Remove a project
|
|
2100
|
-
pan project remove myproject
|
|
2101
|
-
```
|
|
2102
|
-
|
|
2103
|
-
### Context Management
|
|
2104
|
-
|
|
2105
|
-
```bash
|
|
2106
|
-
# Show agent state
|
|
2107
|
-
pan work context state agent-min-123
|
|
2108
|
-
|
|
2109
|
-
# Set a checkpoint
|
|
2110
|
-
pan work context checkpoint "Completed auth module"
|
|
2111
|
-
|
|
2112
|
-
# Search history
|
|
2113
|
-
pan work context history "test"
|
|
2114
|
-
```
|
|
2115
|
-
|
|
2116
|
-
### Agent CVs
|
|
2117
|
-
|
|
2118
|
-
```bash
|
|
2119
|
-
# View an agent's CV (work history)
|
|
2120
|
-
pan work cv agent-min-123
|
|
2121
|
-
|
|
2122
|
-
# Show agent rankings by success rate
|
|
2123
|
-
pan work cv --rankings
|
|
2124
|
-
```
|
|
2125
|
-
|
|
2126
|
-
### Crash Recovery
|
|
2127
|
-
|
|
2128
|
-
```bash
|
|
2129
|
-
# Recover a specific crashed agent
|
|
2130
|
-
pan work recover min-123
|
|
2131
|
-
|
|
2132
|
-
# Auto-recover all crashed agents
|
|
2133
|
-
pan work recover --all
|
|
2134
|
-
```
|
|
2135
|
-
|
|
2136
|
-
### Cloister Commands
|
|
2137
|
-
|
|
2138
|
-
```bash
|
|
2139
|
-
# Start Cloister monitoring service
|
|
2140
|
-
pan cloister start
|
|
2141
|
-
|
|
2142
|
-
# Stop Cloister
|
|
2143
|
-
pan cloister stop
|
|
2144
|
-
|
|
2145
|
-
# Emergency stop all agents (force kill)
|
|
2146
|
-
pan cloister emergency-stop
|
|
2147
|
-
|
|
2148
|
-
# Check Cloister status
|
|
2149
|
-
pan cloister status
|
|
2150
|
-
|
|
2151
|
-
# List all specialists
|
|
2152
|
-
pan specialists list
|
|
2153
|
-
|
|
2154
|
-
# Wake a specialist (resumes previous session if exists)
|
|
2155
|
-
pan specialists wake merge-agent
|
|
2156
|
-
|
|
2157
|
-
# Wake and send a task
|
|
2158
|
-
pan specialists wake merge-agent --task "Review PR #123 for security issues"
|
|
2159
|
-
|
|
2160
|
-
# View specialist queue
|
|
2161
|
-
pan specialists queue merge-agent
|
|
2162
|
-
|
|
2163
|
-
# Reset a single specialist (wipes context)
|
|
2164
|
-
pan specialists reset merge-agent
|
|
2165
|
-
|
|
2166
|
-
# Reset ALL specialists (fresh start)
|
|
2167
|
-
pan specialists reset --all
|
|
2168
|
-
```
|
|
2169
|
-
|
|
2170
|
-
## Dashboard
|
|
2171
|
-
|
|
2172
|
-

|
|
2173
|
-
|
|
2174
|
-
Start the monitoring dashboard:
|
|
2175
|
-
|
|
2176
|
-
```bash
|
|
2177
|
-
pan up
|
|
2178
|
-
```
|
|
2179
|
-
|
|
2180
|
-
**Recommended (containerized with HTTPS):**
|
|
2181
|
-
- Dashboard: https://pan.localhost
|
|
2182
|
-
- Traefik UI: https://traefik.pan.localhost:8082
|
|
2183
|
-
|
|
2184
|
-
This runs everything in Docker containers, avoiding port conflicts with your other projects.
|
|
2185
|
-
|
|
2186
|
-
**Minimal install (no Docker):**
|
|
2187
|
-
```bash
|
|
2188
|
-
pan up --minimal
|
|
2189
|
-
```
|
|
2190
|
-
- Dashboard: http://localhost:3010
|
|
2191
|
-
|
|
2192
|
-
Stop with `pan down`.
|
|
2193
|
-
|
|
2194
|
-
### Dashboard Tabs
|
|
2195
|
-
|
|
2196
|
-
| Tab | Purpose |
|
|
2197
|
-
|-----|---------|
|
|
2198
|
-
| **Board** | Kanban view of Linear issues with drag-and-drop status changes |
|
|
2199
|
-
| **Agents** | Running agent sessions with terminal output |
|
|
2200
|
-
| **Activity** | Real-time `pan` command output log |
|
|
2201
|
-
| **Metrics** | Runtime comparison and cost tracking |
|
|
2202
|
-
| **Skills** | Available skills and their descriptions |
|
|
2203
|
-
| **Health** | System health checks and diagnostics |
|
|
2204
|
-
|
|
2205
|
-
### Issue Filtering
|
|
2206
|
-
|
|
2207
|
-
The dashboard automatically filters issues to reduce visual clutter:
|
|
2208
|
-
|
|
2209
|
-
- **Linear issues** - Shows current cycle issues only
|
|
2210
|
-
- **Done column** - Shows items completed in the last 24 hours
|
|
2211
|
-
- **Canceled column** - Shows items canceled in the last 24 hours
|
|
2212
|
-
|
|
2213
|
-
This filtering applies to both Linear and GitHub issues. Older completed items are excluded from the dashboard but remain in your issue tracker.
|
|
2214
|
-
|
|
2215
|
-
### Issue Cards
|
|
2216
|
-
|
|
2217
|
-
Issue cards on the Kanban board display:
|
|
2218
|
-
|
|
2219
|
-
- **Cost badges** - Color-coded by amount ($0-5 green, $5-20 yellow, $20+ red)
|
|
2220
|
-
- **Container status** - Shows if workspace has Docker containers (running/stopped)
|
|
2221
|
-
- **Agent status** - Indicates if an agent is currently working on the issue
|
|
2222
|
-
- **Workspace status** - Shows if workspace exists, is corrupted, or needs creation
|
|
2223
|
-
|
|
2224
|
-
### Workspace Actions
|
|
2225
|
-
|
|
2226
|
-
Click an issue card to open the workspace detail panel:
|
|
2227
|
-
|
|
2228
|
-
| Button | Action |
|
|
2229
|
-
|--------|--------|
|
|
2230
|
-
| **Create Workspace** | Creates git worktree for the issue |
|
|
2231
|
-
| **Containerize** | Adds Docker containers to an existing workspace |
|
|
2232
|
-
| **Start Containers** | Starts stopped Docker containers |
|
|
2233
|
-
| **Start Planning** | Opens interactive planning session with AI |
|
|
2234
|
-
| **Start Agent** | Spawns autonomous agent in tmux |
|
|
2235
|
-
| **Approve & Merge** | Triggers merge-agent to handle PR merge |
|
|
2236
|
-
|
|
2237
|
-
### Interactive Planning
|
|
2238
|
-
|
|
2239
|
-
The planning dialog provides a real-time terminal for collaborative planning:
|
|
2240
|
-
|
|
2241
|
-
- **Discovery questions** - AI asks clarifying questions before implementation
|
|
2242
|
-
- **Codebase exploration** - AI reads files and understands patterns
|
|
2243
|
-
- **Pull/Push buttons** - Git operations to share planning context with teammates
|
|
2244
|
-
- **AskUserQuestion rendering** - Questions from the AI appear as interactive prompts
|
|
2245
|
-
|
|
2246
|
-
### Metrics & Cost Tracking
|
|
2247
|
-
|
|
2248
|
-
The **Metrics** tab provides insights into AI agent performance and costs:
|
|
2249
|
-
|
|
2250
|
-
- **Per-issue cost badges** - See costs directly on Kanban cards (color-coded by amount)
|
|
2251
|
-
- **Issue cost breakdown** - Click an issue to see detailed costs by model and session
|
|
2252
|
-
- **Runtime comparison** - Compare success rates, duration, and costs across runtimes (Claude, Codex, etc.)
|
|
2253
|
-
- **Capability analysis** - See how different task types (feature, bugfix, refactor) perform
|
|
2254
|
-
|
|
2255
|
-
Cost data is stored in `~/.panopticon/`:
|
|
2256
|
-
- `session-map.json` - Links Claude Code sessions to issues
|
|
2257
|
-
- `runtime-metrics.json` - Aggregated runtime performance data
|
|
2258
|
-
- `costs/` - Raw cost logs
|
|
2259
|
-
|
|
2260
|
-
**API Endpoints:**
|
|
2261
|
-
|
|
2262
|
-
| Endpoint | Description |
|
|
2263
|
-
|----------|-------------|
|
|
2264
|
-
| `GET /api/costs/summary` | Overall cost summary (today/week/month) |
|
|
2265
|
-
| `GET /api/costs/by-issue` | Costs grouped by issue |
|
|
2266
|
-
| `GET /api/issues/:id/costs` | Cost details for a specific issue |
|
|
2267
|
-
| `GET /api/metrics/runtimes` | Runtime comparison metrics |
|
|
2268
|
-
| `GET /api/metrics/tasks` | Recent task history |
|
|
2269
|
-
|
|
2270
|
-
## Skills
|
|
2271
|
-
|
|
2272
|
-
Panopticon ships with 25+ skills organized into categories:
|
|
2273
|
-
|
|
2274
|
-
### Development Workflows
|
|
2275
|
-
|
|
2276
|
-
| Skill | Description |
|
|
2277
|
-
|-------|-------------|
|
|
2278
|
-
| `feature-work` | Standard feature development workflow |
|
|
2279
|
-
| `bug-fix` | Systematic bug investigation and fix |
|
|
2280
|
-
| `refactor` | Safe refactoring with test coverage |
|
|
2281
|
-
| `code-review` | Comprehensive code review checklist |
|
|
2282
|
-
| `code-review-security` | OWASP Top 10 security analysis |
|
|
2283
|
-
| `code-review-performance` | Algorithm and resource optimization |
|
|
2284
|
-
| `release` | Step-by-step release process |
|
|
2285
|
-
| `dependency-update` | Safe dependency updates |
|
|
2286
|
-
| `incident-response` | Production incident handling |
|
|
2287
|
-
| `onboard-codebase` | Understanding new codebases |
|
|
2288
|
-
| `work-complete` | Checklist for completing agent work |
|
|
2289
|
-
|
|
2290
|
-
### AI Self-Monitoring
|
|
2291
|
-
|
|
2292
|
-
| Skill | Description |
|
|
2293
|
-
|-------|-------------|
|
|
2294
|
-
| `knowledge-capture` | Captures learnings when AI gets confused or corrected |
|
|
2295
|
-
| `refactor-radar` | Detects systemic issues causing AI confusion |
|
|
2296
|
-
| `session-health` | Detect and clean up stuck sessions |
|
|
2297
|
-
|
|
2298
|
-
### Panopticon Operations (pan-*)
|
|
2299
|
-
|
|
2300
|
-
| Skill | Description |
|
|
2301
|
-
|-------|-------------|
|
|
2302
|
-
| `pan-help` | Show all Panopticon commands |
|
|
2303
|
-
| `pan-up` | Start dashboard and services |
|
|
2304
|
-
| `pan-down` | Stop dashboard and services |
|
|
2305
|
-
| `pan-status` | Show running agents |
|
|
2306
|
-
| `pan-issue` | Spawn agent for an issue |
|
|
2307
|
-
| `pan-plan` | Create execution plan for issue |
|
|
2308
|
-
| `pan-tell` | Send message to running agent |
|
|
2309
|
-
| `pan-kill` | Kill a running agent |
|
|
2310
|
-
| `pan-approve` | Approve agent work and merge |
|
|
2311
|
-
| `pan-health` | Check system health |
|
|
2312
|
-
| `pan-sync` | Sync skills to AI tools |
|
|
2313
|
-
| `pan-install` | Install prerequisites |
|
|
2314
|
-
| `pan-setup` | Initial setup wizard |
|
|
2315
|
-
| `pan-quickstart` | Quick start guide |
|
|
2316
|
-
| `pan-projects` | Manage registered projects |
|
|
2317
|
-
| `pan-tracker` | Issue tracker operations |
|
|
2318
|
-
| `pan-logs` | View agent logs |
|
|
2319
|
-
| `pan-rescue` | Recover crashed agents |
|
|
2320
|
-
| `pan-diagnose` | Diagnose agent issues |
|
|
2321
|
-
| `pan-docker` | Docker operations |
|
|
2322
|
-
| `pan-network` | Network diagnostics |
|
|
2323
|
-
| `pan-config` | Configuration management |
|
|
2324
|
-
| `pan-restart` | Safely restart Panopticon dashboard and services |
|
|
2325
|
-
| `pan-code-review` | Orchestrate parallel code review (3 reviewers + synthesis) |
|
|
2326
|
-
| `pan-convoy-synthesis` | Synthesize convoy coordination |
|
|
2327
|
-
| `pan-subagent-creator` | Create specialized subagents |
|
|
2328
|
-
| `pan-skill-creator` | Create new skills (guided) |
|
|
2329
|
-
| `pan-workspace-config` | Configure polyrepo workspaces, DNS, ports |
|
|
2330
|
-
| `pan-test-config` | Configure project test suites |
|
|
2331
|
-
|
|
2332
|
-
### Utilities
|
|
2333
|
-
|
|
2334
|
-
| Skill | Description |
|
|
2335
|
-
|-------|-------------|
|
|
2336
|
-
| `beads` | Git-backed issue tracking with dependencies |
|
|
2337
|
-
| `skill-creator` | Guide for creating new skills |
|
|
2338
|
-
| `web-design-guidelines` | UI/UX review checklist |
|
|
2339
|
-
|
|
2340
|
-
## Subagents
|
|
2341
|
-
|
|
2342
|
-
Panopticon includes specialized subagent templates for common development tasks. Subagents are invoked via the Task tool or convoy orchestration for parallel execution.
|
|
2343
|
-
|
|
2344
|
-
### Code Review Subagents
|
|
2345
|
-
|
|
2346
|
-
| Subagent | Model | Focus | Output |
|
|
2347
|
-
|----------|-------|-------|--------|
|
|
2348
|
-
| `code-review-correctness` | haiku | Logic errors, edge cases, type safety | `.claude/reviews/<timestamp>-correctness.md` |
|
|
2349
|
-
| `code-review-security` | sonnet | OWASP Top 10, vulnerabilities | `.claude/reviews/<timestamp>-security.md` |
|
|
2350
|
-
| `code-review-performance` | haiku | Algorithms, N+1 queries, memory | `.claude/reviews/<timestamp>-performance.md` |
|
|
2351
|
-
| `code-review-synthesis` | sonnet | Combines all findings into unified report | `.claude/reviews/<timestamp>-synthesis.md` |
|
|
2352
|
-
|
|
2353
|
-
**Usage Example:**
|
|
2354
|
-
```bash
|
|
2355
|
-
/pan-code-review --files "src/auth/*.ts"
|
|
2356
|
-
```
|
|
2357
|
-
|
|
2358
|
-
This spawns all three reviewers in parallel, then synthesizes their findings into a prioritized report.
|
|
2359
|
-
|
|
2360
|
-
### Planning & Exploration Subagents
|
|
2361
|
-
|
|
2362
|
-
| Subagent | Model | Focus | Permission Mode |
|
|
2363
|
-
|----------|-------|-------|-----------------|
|
|
2364
|
-
| `planning-agent` | sonnet | Codebase research, execution planning | `plan` (read-only) |
|
|
2365
|
-
| `codebase-explorer` | haiku | Fast architecture discovery, pattern finding | `plan` (read-only) |
|
|
2366
|
-
| `triage-agent` | haiku | Issue categorization, complexity estimation | default |
|
|
2367
|
-
| `health-monitor` | haiku | Agent stuck detection, log analysis | default |
|
|
2368
|
-
|
|
2369
|
-
**Usage Examples:**
|
|
2370
|
-
```bash
|
|
2371
|
-
# Explore codebase architecture
|
|
2372
|
-
Task(subagent_type='codebase-explorer', prompt='Map out the authentication system')
|
|
2373
|
-
|
|
2374
|
-
# Triage an issue
|
|
2375
|
-
Task(subagent_type='triage-agent', prompt='Categorize and estimate ISSUE-123')
|
|
2376
|
-
|
|
2377
|
-
# Check agent health
|
|
2378
|
-
Task(subagent_type='health-monitor', prompt='Check status of all running agents')
|
|
2379
|
-
```
|
|
2380
|
-
|
|
2381
|
-
### Parallel Code Review Workflow
|
|
2382
|
-
|
|
2383
|
-
The `/pan-code-review` skill orchestrates a comprehensive parallel review:
|
|
2384
|
-
|
|
2385
|
-
```
|
|
2386
|
-
1. Determine scope (git diff, files, or branch)
|
|
2387
|
-
2. Spawn 3 parallel reviewers:
|
|
2388
|
-
├─→ correctness (logic, types)
|
|
2389
|
-
├─→ security (vulnerabilities)
|
|
2390
|
-
└─→ performance (bottlenecks)
|
|
2391
|
-
3. Each writes findings to .claude/reviews/
|
|
2392
|
-
4. Spawn synthesis agent
|
|
2393
|
-
5. Synthesis combines all findings
|
|
2394
|
-
6. Present unified, prioritized report
|
|
2395
|
-
```
|
|
2396
|
-
|
|
2397
|
-
**Benefits:**
|
|
2398
|
-
- **3x faster** than sequential reviews
|
|
2399
|
-
- **Comprehensive coverage** across all dimensions
|
|
2400
|
-
- **Prioritized findings** (blocker > critical > high > medium > low)
|
|
2401
|
-
- **Actionable recommendations** with code examples
|
|
2402
|
-
|
|
2403
|
-
**Review Output:**
|
|
2404
|
-
```markdown
|
|
2405
|
-
# Code Review - Complete Analysis
|
|
2406
|
-
|
|
2407
|
-
## Executive Summary
|
|
2408
|
-
**Overall Assessment:** Needs Major Revisions
|
|
2409
|
-
**Key Findings:**
|
|
2410
|
-
- 1 blocker (SQL injection)
|
|
2411
|
-
- 4 critical issues
|
|
2412
|
-
- 6 high-priority items
|
|
2413
|
-
|
|
2414
|
-
## Blocker Issues
|
|
2415
|
-
### 1. [Security] SQL Injection in login endpoint
|
|
2416
|
-
...
|
|
2417
|
-
|
|
2418
|
-
## Critical Issues
|
|
2419
|
-
...
|
|
2420
|
-
```
|
|
2421
|
-
|
|
2422
|
-
### Creating Custom Subagents
|
|
2423
|
-
|
|
2424
|
-
Use the `/pan-subagent-creator` skill to create project-specific subagents:
|
|
2425
|
-
|
|
2426
|
-
```bash
|
|
2427
|
-
/pan-subagent-creator
|
|
2428
|
-
```
|
|
2429
|
-
|
|
2430
|
-
Subagent templates live in `~/.panopticon/agents/` and sync to `~/.claude/agents/`.
|
|
2431
|
-
|
|
2432
|
-
### Reserved Skill Names
|
|
2433
|
-
|
|
2434
|
-
Panopticon reserves all skill names listed above. **Do not use these names for project-specific skills** to avoid conflicts.
|
|
2435
|
-
|
|
2436
|
-
**Recommendation:** Use a project-specific prefix for your skills (e.g., `myn-standards`, `acme-deployment`) to avoid namespace collisions.
|
|
2437
|
-
|
|
2438
|
-
### Project-Specific Skills
|
|
2439
|
-
|
|
2440
|
-
Projects can have their own skills alongside Panopticon's:
|
|
2441
|
-
|
|
2442
|
-
```
|
|
2443
|
-
~/.claude/skills/
|
|
2444
|
-
├── pan-help/ # Symlink → ~/.panopticon/skills/pan-help/
|
|
2445
|
-
├── feature-work/ # Symlink → ~/.panopticon/skills/feature-work/
|
|
2446
|
-
└── ... (other pan skills)
|
|
2447
|
-
|
|
2448
|
-
{project}/.claude/skills/
|
|
2449
|
-
├── myn-standards/ # Project-specific (git-tracked)
|
|
2450
|
-
└── myn-api-patterns/ # Project-specific (git-tracked)
|
|
2451
|
-
```
|
|
2452
|
-
|
|
2453
|
-
Project-specific skills in `{project}/.claude/skills/` are **not managed by Panopticon**. They live in your project's git repo and take precedence over global skills with the same name.
|
|
2454
|
-
|
|
2455
|
-
### Skill Distribution
|
|
2456
|
-
|
|
2457
|
-
Skills are synced to all supported AI tools via symlinks:
|
|
2458
|
-
|
|
2459
|
-
```bash
|
|
2460
|
-
~/.panopticon/skills/ # Canonical source
|
|
2461
|
-
↓ pan sync
|
|
2462
|
-
~/.claude/skills/ # Claude Code + Cursor
|
|
2463
|
-
~/.codex/skills/ # Codex
|
|
2464
|
-
~/.gemini/skills/ # Gemini CLI
|
|
2465
|
-
```
|
|
2466
|
-
|
|
2467
|
-
## PRD Convention
|
|
2468
|
-
|
|
2469
|
-
Panopticon enforces a standard approach to Product Requirements Documents (PRDs) across all managed projects.
|
|
2470
|
-
|
|
2471
|
-
### PRD Structure
|
|
2472
|
-
|
|
2473
|
-
Every project has a **canonical PRD** that defines the core product:
|
|
2474
|
-
|
|
2475
|
-
```
|
|
2476
|
-
{project}/
|
|
2477
|
-
├── docs/
|
|
2478
|
-
│ └── PRD.md # The canonical PRD (core product definition)
|
|
2479
|
-
├── workspaces/
|
|
2480
|
-
│ └── feature-{issue}/
|
|
2481
|
-
│ └── docs/
|
|
2482
|
-
│ └── {ISSUE}-plan.md # Feature PRD (lives in feature branch)
|
|
2483
|
-
```
|
|
2484
|
-
|
|
2485
|
-
| PRD Type | Location | Purpose |
|
|
2486
|
-
|----------|----------|---------|
|
|
2487
|
-
| **Canonical PRD** | `docs/PRD.md` | Core product definition, always on main |
|
|
2488
|
-
| **Feature PRD** | `workspaces/feature-{issue}/docs/{ISSUE}-plan.md` | Feature spec, lives in feature branch, merged with PR |
|
|
2489
|
-
|
|
2490
|
-
### Feature PRDs Live in Workspaces
|
|
2491
|
-
|
|
2492
|
-
When you start planning an issue, Panopticon creates:
|
|
2493
|
-
1. A git worktree (workspace) for the feature branch
|
|
2494
|
-
2. A planning session that generates a feature PRD
|
|
2495
|
-
|
|
2496
|
-
The feature PRD **lives in the workspace** (feature branch) because:
|
|
2497
|
-
- It gets merged with the PR (documentation travels with code)
|
|
2498
|
-
- If you abort planning and delete the workspace, you don't want orphaned PRDs
|
|
2499
|
-
- Clean separation - each feature is self-contained
|
|
2500
|
-
|
|
2501
|
-
### Project Initialization
|
|
2502
|
-
|
|
2503
|
-
When registering a new project with Panopticon (`pan project add`), the system will:
|
|
2504
|
-
|
|
2505
|
-
1. **Check for existing PRD** - Look for `docs/PRD.md`, `PRD.md`, `README.md`, or similar
|
|
2506
|
-
2. **If found**: Use it to create/update the canonical PRD format, prompting for any missing crucial information
|
|
2507
|
-
3. **If not found**: Generate one by:
|
|
2508
|
-
- Analyzing the codebase structure
|
|
2509
|
-
- Identifying key technologies and patterns
|
|
2510
|
-
- Asking discovery questions about the product
|
|
2511
|
-
|
|
2512
|
-
This ensures every Panopticon-managed project has a well-defined canonical PRD that agents can reference.
|
|
2513
|
-
|
|
2514
|
-
### PRD Naming Convention
|
|
2515
|
-
|
|
2516
|
-
| Document | Naming | Example |
|
|
2517
|
-
|----------|--------|---------|
|
|
2518
|
-
| Canonical PRD | `PRD.md` | `docs/PRD.md` |
|
|
2519
|
-
| Feature PRD | `{ISSUE}-plan.md` | `MIN-123-plan.md`, `PAN-4-plan.md` |
|
|
2520
|
-
| Planning artifacts | In `.planning/{issue}/` | `.planning/min-123/STATE.md` |
|
|
2521
|
-
|
|
2522
|
-
## Architecture
|
|
2523
|
-
|
|
2524
|
-
```
|
|
2525
|
-
~/.panopticon/
|
|
2526
|
-
config.toml # Main configuration
|
|
2527
|
-
projects.yaml # Multi-project registry with issue routing
|
|
2528
|
-
project-mappings.json # Linear project → local path mappings (legacy)
|
|
2529
|
-
session-map.json # Claude sessions → issue linking
|
|
2530
|
-
runtime-metrics.json # Runtime performance metrics
|
|
2531
|
-
|
|
2532
|
-
skills/ # Shared skills (SKILL.md format)
|
|
2533
|
-
commands/ # Slash commands
|
|
2534
|
-
agents/ # Subagent templates (.md files)
|
|
2535
|
-
bin/ # Hook scripts (synced via pan sync)
|
|
2536
|
-
heartbeat-hook # Real-time activity monitoring hook
|
|
2537
|
-
|
|
2538
|
-
agents/ # Per-agent runtime state
|
|
2539
|
-
agent-min-123/
|
|
2540
|
-
state.json # Agent state (model, phase, complexity)
|
|
2541
|
-
health.json # Health status
|
|
2542
|
-
hook.json # FPP work queue
|
|
2543
|
-
cv.json # Work history
|
|
2544
|
-
mail/ # Incoming messages
|
|
2545
|
-
handoffs/ # Handoff prompts (for debugging)
|
|
2546
|
-
|
|
2547
|
-
cloister/ # Cloister AI lifecycle manager
|
|
2548
|
-
config.json # Cloister settings
|
|
2549
|
-
state.json # Running state
|
|
2550
|
-
events.jsonl # Handoff event log
|
|
2551
|
-
|
|
2552
|
-
heartbeats/ # Real-time agent activity
|
|
2553
|
-
agent-min-123.json # Last heartbeat from agent
|
|
2554
|
-
|
|
2555
|
-
logs/ # Log files
|
|
2556
|
-
handoffs.jsonl # All handoff events (for analytics)
|
|
2557
|
-
|
|
2558
|
-
costs/ # Raw cost logs (JSONL)
|
|
2559
|
-
backups/ # Sync backups
|
|
2560
|
-
traefik/ # Traefik reverse proxy config
|
|
2561
|
-
dynamic/ # Dynamic route configs
|
|
2562
|
-
certs/ # TLS certificates
|
|
2563
|
-
```
|
|
2564
|
-
|
|
2565
|
-
### Agent State Management
|
|
2566
|
-
|
|
2567
|
-
Each agent's state is tracked in `~/.panopticon/agents/{agent-id}/state.json`:
|
|
2568
|
-
|
|
2569
|
-
```json
|
|
2570
|
-
{
|
|
2571
|
-
"id": "agent-min-123",
|
|
2572
|
-
"issueId": "MIN-123",
|
|
2573
|
-
"workspace": "/home/user/projects/myapp/workspaces/feature-min-123",
|
|
2574
|
-
"branch": "feature/min-123",
|
|
2575
|
-
"phase": "implementation",
|
|
2576
|
-
"model": "sonnet",
|
|
2577
|
-
"complexity": "medium",
|
|
2578
|
-
"handoffCount": 0,
|
|
2579
|
-
"sessionId": "abc123",
|
|
2580
|
-
"createdAt": "2024-01-22T10:00:00-08:00",
|
|
2581
|
-
"updatedAt": "2024-01-22T10:30:00-08:00"
|
|
2582
|
-
}
|
|
2583
|
-
```
|
|
2584
|
-
|
|
2585
|
-
| Field | Description |
|
|
2586
|
-
|-------|-------------|
|
|
2587
|
-
| `phase` | Current work phase: `planning`, `implementation`, `testing`, `review`, `merging` |
|
|
2588
|
-
| `model` | Current model: `haiku`, `sonnet`, `opus` |
|
|
2589
|
-
| `complexity` | Detected complexity: `trivial`, `simple`, `medium`, `complex`, `expert` |
|
|
2590
|
-
| `handoffCount` | Number of times the agent has been handed off to a different model |
|
|
2591
|
-
| `sessionId` | Claude Code session ID (for resuming after handoff) |
|
|
2592
|
-
|
|
2593
|
-
**State Cleanup:** When an agent is killed or aborted (`pan work kill`), Panopticon automatically cleans up its state files to prevent stale data from affecting future runs.
|
|
2594
|
-
|
|
2595
|
-
### Deep Wipe
|
|
2596
|
-
|
|
2597
|
-
For issues that get into a stuck or inconsistent state, use `pan work wipe` to completely reset:
|
|
2598
|
-
|
|
2599
|
-
```bash
|
|
2600
|
-
pan work wipe MIN-123 # Basic cleanup
|
|
2601
|
-
pan work wipe MIN-123 -w # Also delete workspace
|
|
2602
|
-
pan work wipe MIN-123 -y -w # Skip confirmation
|
|
2603
|
-
```
|
|
2604
|
-
|
|
2605
|
-
**Deep wipe cleans up:**
|
|
2606
|
-
- Tmux sessions (`planning-min-123`, `agent-min-123`)
|
|
2607
|
-
- Agent state directories (`~/.panopticon/agents/planning-*`, `agent-*`)
|
|
2608
|
-
- Legacy planning directories (`project/.planning/min-123/`)
|
|
2609
|
-
- Workspace (if `-w` flag is used)
|
|
2610
|
-
- Linear issue status (reset to Backlog)
|
|
2611
|
-
- Linear labels (removes "Review Ready", "Planning")
|
|
2612
|
-
|
|
2613
|
-
**Dashboard UI:** When aborting planning, click "🔥 Deep Wipe" for a complete reset.
|
|
2614
|
-
|
|
2615
|
-
## Health Monitoring (Deacon Pattern)
|
|
2616
|
-
|
|
2617
|
-
Panopticon implements the Deacon pattern for stuck agent detection:
|
|
2618
|
-
|
|
2619
|
-
- **Ping timeout**: 30 seconds
|
|
2620
|
-
- **Consecutive failures**: 3 before recovery
|
|
2621
|
-
- **Cooldown**: 5 minutes between force-kills
|
|
2622
|
-
|
|
2623
|
-
When an agent is stuck (no activity for 30+ minutes), Panopticon will:
|
|
2624
|
-
1. Force kill the tmux session
|
|
2625
|
-
2. Record the kill in health.json
|
|
2626
|
-
3. Respawn with crash recovery context
|
|
2627
|
-
|
|
2628
|
-
## FPP (Fixed Point Principle)
|
|
2629
|
-
|
|
2630
|
-
> "Any runnable action is a fixed point and must resolve before the system can rest."
|
|
2631
|
-
|
|
2632
|
-
*Inspired by Doctor Who: a fixed point in time must occur — it cannot be avoided.*
|
|
2633
|
-
|
|
2634
|
-
**Fixed Point Principle (FPP):** Any runnable bead, hook, or agent action represents a fixed point in execution and must be resolved immediately. Panopticon continues executing until no fixed points remain.
|
|
2635
|
-
|
|
2636
|
-
FPP ensures agents are self-propelling:
|
|
2637
|
-
1. Work items are pushed to the agent's hook
|
|
2638
|
-
2. On spawn/recovery, the hook is checked
|
|
2639
|
-
3. Pending work is injected into the agent's prompt
|
|
2640
|
-
4. Completed work is popped from the hook
|
|
2641
|
-
|
|
2642
|
-
## Development
|
|
2643
|
-
|
|
2644
|
-
### Dev vs Production Strategy
|
|
2645
|
-
|
|
2646
|
-
Panopticon uses a **shared config, switchable CLI** approach:
|
|
2647
|
-
|
|
2648
|
-
```
|
|
2649
|
-
~/.panopticon/ # Shared by both dev and prod
|
|
2650
|
-
├── config.toml # Settings
|
|
2651
|
-
├── projects.json # Registered projects
|
|
2652
|
-
├── project-mappings.json # Linear → local path mappings
|
|
2653
|
-
├── agents/ # Agent state
|
|
2654
|
-
└── skills/ # Shared skills
|
|
2655
|
-
```
|
|
2656
|
-
|
|
2657
|
-
Both dev and production versions read/write the same config, so you can switch between them freely.
|
|
2658
|
-
|
|
2659
|
-
### Running in Development Mode
|
|
2660
|
-
|
|
2661
|
-
```bash
|
|
2662
|
-
# Clone and setup
|
|
2663
|
-
git clone https://github.com/eltmon/panopticon.git
|
|
2664
|
-
cd panopticon
|
|
2665
|
-
npm install
|
|
2666
|
-
|
|
2667
|
-
# Link dev version globally (makes 'pan' use your local code)
|
|
2668
|
-
npm link
|
|
2669
|
-
|
|
2670
|
-
# Start the dashboard (with hot reload)
|
|
2671
|
-
cd src/dashboard
|
|
2672
|
-
npm run install:all
|
|
2673
|
-
npm run dev
|
|
2674
|
-
# → Frontend: http://localhost:3010
|
|
2675
|
-
# → API: http://localhost:3011
|
|
2676
|
-
```
|
|
2677
|
-
|
|
2678
|
-
### Switching Between Dev and Prod
|
|
2679
|
-
|
|
2680
|
-
```bash
|
|
2681
|
-
# Use dev version (from your local repo)
|
|
2682
|
-
cd /path/to/panopticon && npm link
|
|
2683
|
-
|
|
2684
|
-
# Switch back to stable release
|
|
2685
|
-
npm unlink panopticon-cli
|
|
2686
|
-
npm install -g panopticon-cli
|
|
2687
|
-
```
|
|
2688
|
-
|
|
2689
|
-
### Dashboard Modes
|
|
2690
|
-
|
|
2691
|
-
| Mode | Command | Use Case |
|
|
2692
|
-
|------|---------|----------|
|
|
2693
|
-
| **Production** | `pan up` | Daily usage, containerized, HTTPS at https://pan.localhost |
|
|
2694
|
-
| **Dev** | `cd src/dashboard && npm run dev` | Only for active development on Panopticon itself |
|
|
2695
|
-
|
|
2696
|
-
**Note:** Use `pan up` for normal usage - it runs in Docker and won't conflict with your project's ports. Only use dev mode when actively working on Panopticon's codebase.
|
|
2697
|
-
|
|
2698
|
-
### Working on Panopticon While Using It
|
|
2699
|
-
|
|
2700
|
-
If you're both developing Panopticon AND using it for your own projects:
|
|
2701
|
-
|
|
2702
|
-
1. **Use `npm link`** so CLI changes take effect immediately
|
|
2703
|
-
2. **Run dashboard from source** for hot reload on UI changes
|
|
2704
|
-
3. **Config is shared** - workspaces/agents work the same either way
|
|
2705
|
-
4. **Test in a real project** - your own usage is the best test
|
|
2706
|
-
|
|
2707
|
-
### Developer Skills (dev-skills/)
|
|
2708
|
-
|
|
2709
|
-
Panopticon has two types of skills:
|
|
2710
|
-
|
|
2711
|
-
| Directory | Purpose | Synced When |
|
|
2712
|
-
|-----------|---------|-------------|
|
|
2713
|
-
| `skills/` | User-facing skills for all Panopticon users | Always via `pan sync` |
|
|
2714
|
-
| `dev-skills/` | Developer-only skills for Panopticon contributors | Only in dev mode |
|
|
2715
|
-
|
|
2716
|
-
**Dev mode is automatically detected** when running from the Panopticon source repo (npm link). Skills in `dev-skills/` are:
|
|
2717
|
-
- Checked into the repo and version-controlled
|
|
2718
|
-
- Only synced to developers' machines, not end users
|
|
2719
|
-
- Shown with `[dev]` label in `pan sync --dry-run`
|
|
2720
|
-
|
|
2721
|
-
```bash
|
|
2722
|
-
# Check what will be synced (including dev-skills)
|
|
2723
|
-
pan sync --dry-run
|
|
2724
|
-
|
|
2725
|
-
# Output shows:
|
|
2726
|
-
# Developer mode detected - dev-skills will be synced
|
|
2727
|
-
# ...
|
|
2728
|
-
# + skill/test-specialist-workflow [dev]
|
|
2729
|
-
```
|
|
2730
|
-
|
|
2731
|
-
### Testing the Specialist System
|
|
2732
|
-
|
|
2733
|
-
The `test-specialist-workflow` skill provides end-to-end testing for the specialist handoff pipeline.
|
|
2734
|
-
|
|
2735
|
-
**Location:** `dev-skills/test-specialist-workflow/SKILL.md`
|
|
2736
|
-
|
|
2737
|
-
**What it tests:**
|
|
2738
|
-
- Full approve workflow: review-agent → test-agent → merge-agent
|
|
2739
|
-
- Specialist handoffs via `pan specialists wake --task`
|
|
2740
|
-
- Merge completion and branch preservation
|
|
2741
|
-
|
|
2742
|
-
**Usage:**
|
|
2743
|
-
|
|
2744
|
-
```bash
|
|
2745
|
-
# First sync to get dev-skills
|
|
2746
|
-
pan sync
|
|
2747
|
-
|
|
2748
|
-
# In Claude Code, invoke the skill
|
|
2749
|
-
/test-specialist-workflow
|
|
2750
|
-
```
|
|
2751
|
-
|
|
2752
|
-
The skill guides you through:
|
|
2753
|
-
|
|
2754
|
-
1. **Prerequisites check** - Dashboard running, specialists available
|
|
2755
|
-
2. **Create test issue** - GitHub issue for tracking
|
|
2756
|
-
3. **Create workspace** - Git worktree for the test
|
|
2757
|
-
4. **Make test change** - Trivial commit to verify merge
|
|
2758
|
-
5. **Trigger approve** - Kicks off the specialist pipeline
|
|
2759
|
-
6. **Monitor handoffs** - Watch each specialist complete and hand off
|
|
2760
|
-
7. **Verify merge** - Confirm change reached main branch
|
|
2761
|
-
8. **Cleanup** - Close issue, remove workspace
|
|
2762
|
-
|
|
2763
|
-
**Expected timeline:** 2-4 minutes total
|
|
2764
|
-
|
|
2765
|
-
**When to use:**
|
|
2766
|
-
- After making changes to the specialist system
|
|
2767
|
-
- After modifying the approve workflow
|
|
2768
|
-
- As a smoke test before releases
|
|
2769
|
-
|
|
2770
|
-
## Troubleshooting
|
|
2771
|
-
|
|
2772
|
-
### WSL2 Stability Issues (Windows Users)
|
|
2773
|
-
|
|
2774
|
-
WSL2 can experience crashes and networking issues, especially under heavy AI agent workloads. Here are recommended `.wslconfig` settings to improve stability.
|
|
2775
|
-
|
|
2776
|
-
**Create/edit `C:\Users\<username>\.wslconfig`:**
|
|
2777
|
-
|
|
2778
|
-
```ini
|
|
2779
|
-
[wsl2]
|
|
2780
|
-
# Resource allocation (adjust based on your system)
|
|
2781
|
-
memory=40GB
|
|
2782
|
-
processors=18
|
|
2783
|
-
swap=8GB
|
|
2784
|
-
|
|
2785
|
-
# Localhost forwarding between Windows and WSL
|
|
2786
|
-
localhostForwarding=true
|
|
2787
|
-
|
|
2788
|
-
# Disable GPU/GUI passthrough - reduces dxg driver errors
|
|
2789
|
-
guiApplications=false
|
|
2790
|
-
|
|
2791
|
-
# ============================================================
|
|
2792
|
-
# WINDOWS 11 ONLY - Comment these out on Windows 10!
|
|
2793
|
-
# These settings require Windows 11 22H2 or later.
|
|
2794
|
-
# On Windows 10 they are silently ignored or may cause issues.
|
|
2795
|
-
# ============================================================
|
|
2796
|
-
|
|
2797
|
-
# Route DNS through Windows - prevents getaddrinfo() failures
|
|
2798
|
-
# dnsTunneling=true # Windows 11 only
|
|
2799
|
-
|
|
2800
|
-
# Inherit Windows proxy settings
|
|
2801
|
-
# autoProxy=true # Windows 11 only
|
|
2802
|
-
|
|
2803
|
-
# Aggressively reclaim cached memory
|
|
2804
|
-
# autoMemoryReclaim=dropCache # Windows 11 only
|
|
2805
|
-
|
|
2806
|
-
# Use sparse VHD to allow better memory compaction
|
|
2807
|
-
# sparseVhd=true # Windows 11 only
|
|
2808
|
-
|
|
2809
|
-
# Mirrored networking (may conflict with Docker Desktop)
|
|
2810
|
-
# networkingMode=mirrored # Windows 11 only
|
|
2811
|
-
```
|
|
2812
|
-
|
|
2813
|
-
**After changing `.wslconfig`:**
|
|
2814
|
-
```powershell
|
|
2815
|
-
wsl --shutdown
|
|
2816
|
-
# Then relaunch your WSL terminal
|
|
2817
|
-
```
|
|
2818
|
-
|
|
2819
|
-
**Verify settings applied:**
|
|
2820
|
-
```bash
|
|
2821
|
-
# Check resources
|
|
2822
|
-
free -h # Should show configured memory
|
|
2823
|
-
nproc # Should show configured processors
|
|
2824
|
-
swapon --show # Should show configured swap
|
|
2825
|
-
|
|
2826
|
-
# Check networking mode (Windows 11 only)
|
|
2827
|
-
ip addr show eth0 # NAT mode shows 172.x.x.x IP
|
|
2828
|
-
# Mirrored mode shares Windows network directly
|
|
2829
|
-
```
|
|
2830
|
-
|
|
2831
|
-
#### Windows 10 Limitations
|
|
2832
|
-
|
|
2833
|
-
| Feature | Windows 10 | Windows 11 22H2+ |
|
|
2834
|
-
|---------|-----------|------------------|
|
|
2835
|
-
| `memory`, `processors`, `swap` | ✅ Works | ✅ Works |
|
|
2836
|
-
| `localhostForwarding` | ✅ Works | ✅ Works |
|
|
2837
|
-
| `guiApplications=false` | ✅ Works | ✅ Works |
|
|
2838
|
-
| `networkingMode=mirrored` | ❌ Not supported | ✅ Supported |
|
|
2839
|
-
| `dnsTunneling=true` | ❌ Not supported | ✅ Supported |
|
|
2840
|
-
| `autoProxy=true` | ❌ Not supported | ✅ Supported |
|
|
2841
|
-
| `autoMemoryReclaim` | ❌ Not supported | ✅ Supported |
|
|
2842
|
-
| `sparseVhd=true` | ❌ Not supported | ✅ Supported |
|
|
2843
|
-
|
|
2844
|
-
**Windows 10 users:** Most advanced WSL2 features require Windows 11. On Windows 10, only the basic resource limits and `localhostForwarding`/`guiApplications` settings are supported. Other settings will be silently ignored or may cause instability.
|
|
2845
|
-
|
|
2846
|
-
If you experience frequent WSL2 crashes on Windows 10, consider:
|
|
2847
|
-
- Using only the basic settings shown above (memory, processors, swap, localhostForwarding, guiApplications)
|
|
2848
|
-
- Reducing `memory` allocation if system is under pressure
|
|
2849
|
-
- Upgrading to Windows 11 for full WSL2 feature support
|
|
2850
|
-
- Checking Windows Event Viewer for specific crash causes
|
|
2851
|
-
|
|
2852
|
-
#### Additional Windows 10 Workarounds
|
|
2853
|
-
|
|
2854
|
-
If NAT networking is unstable on Windows 10:
|
|
2855
|
-
|
|
2856
|
-
```powershell
|
|
2857
|
-
# 1. Update WSL to latest version
|
|
2858
|
-
wsl --update
|
|
2859
|
-
|
|
2860
|
-
# 2. Check for VPN/firewall conflicts
|
|
2861
|
-
# Disable VPN temporarily to test if it's causing issues
|
|
2862
|
-
|
|
2863
|
-
# 3. Reset Windows network stack (run as Admin)
|
|
2864
|
-
netsh winsock reset
|
|
2865
|
-
netsh int ip reset
|
|
2866
|
-
|
|
2867
|
-
# 4. Restart after network reset
|
|
2868
|
-
Restart-Computer
|
|
2869
|
-
```
|
|
2870
|
-
|
|
2871
|
-
**Common conflict sources:**
|
|
2872
|
-
- VPN clients (especially corporate VPNs)
|
|
2873
|
-
- Docker Desktop (can conflict with WSL networking)
|
|
2874
|
-
- Third-party firewalls
|
|
2875
|
-
- Hyper-V virtual switch issues
|
|
2876
|
-
|
|
2877
|
-
**If NAT fails completely**, WSL 2.3.25+ automatically falls back to VirtioProxy mode. This is less performant but more stable. You'll see: `"Failed to configure network (networkingMode Nat), falling back to networkingMode VirtioProxy."`
|
|
2878
|
-
|
|
2879
|
-
**References:**
|
|
2880
|
-
- [Microsoft WSL Networking Documentation](https://learn.microsoft.com/en-us/windows/wsl/networking)
|
|
2881
|
-
- [WSL GitHub Issues - Networking](https://github.com/microsoft/WSL/issues?q=networking+mirrored)
|
|
2882
|
-
- [WSL NAT Fallback Issue #12297](https://github.com/microsoft/WSL/issues/12297)
|
|
2883
|
-
|
|
2884
|
-
### Slow Vite/React Frontend with Multiple Workspaces
|
|
2885
|
-
|
|
2886
|
-
If running multiple containerized workspaces with Vite/React frontends, you may notice CPU spikes and slow HMR. This is because Vite's default file watching polls every 100ms, which compounds with multiple instances.
|
|
2887
|
-
|
|
2888
|
-
**Fix:** Increase the polling interval in your `vite.config.mjs`:
|
|
2889
|
-
|
|
2890
|
-
```javascript
|
|
2891
|
-
server: {
|
|
2892
|
-
watch: {
|
|
2893
|
-
usePolling: true,
|
|
2894
|
-
interval: 3000, // Poll every 3s instead of 100ms default
|
|
2895
|
-
},
|
|
2896
|
-
}
|
|
2897
|
-
```
|
|
2898
|
-
|
|
2899
|
-
A 3000ms interval supports 4-5 concurrent workspaces comfortably while maintaining acceptable HMR responsiveness.
|
|
2900
|
-
|
|
2901
|
-
### Corrupted Workspaces
|
|
2902
|
-
|
|
2903
|
-
A workspace can become "corrupted" when it exists as a directory but is no longer a valid git worktree. The dashboard will show a yellow "Workspace Corrupted" warning with an option to clean and recreate.
|
|
2904
|
-
|
|
2905
|
-
**Symptoms:**
|
|
2906
|
-
- Dashboard shows "Workspace Corrupted" warning
|
|
2907
|
-
- `git status` in the workspace fails with "not a git repository"
|
|
2908
|
-
- The `.git` file is missing from the workspace directory
|
|
2909
|
-
|
|
2910
|
-
**Common Causes:**
|
|
2911
|
-
|
|
2912
|
-
| Cause | Description |
|
|
2913
|
-
|-------|-------------|
|
|
2914
|
-
| **Interrupted creation** | `pan workspace create` was killed mid-execution (Ctrl+C, system crash) |
|
|
2915
|
-
| **Manual .git deletion** | Someone accidentally deleted the `.git` file in the workspace |
|
|
2916
|
-
| **Disk space issues** | Ran out of disk space during workspace creation |
|
|
2917
|
-
| **Git worktree pruning** | Running `git worktree prune` in the main repo removed the worktree link |
|
|
2918
|
-
| **Force-deleted main repo** | The main repository was moved or deleted while workspaces existed |
|
|
2919
|
-
|
|
2920
|
-
**Resolution:**
|
|
2921
|
-
|
|
2922
|
-
1. **Via Dashboard (recommended):**
|
|
2923
|
-
- Click on the issue to open the detail panel
|
|
2924
|
-
- Click "Clean & Recreate" button
|
|
2925
|
-
- Review the files that will be deleted
|
|
2926
|
-
- Check "Create backup" to preserve your work (recommended)
|
|
2927
|
-
- Click "Backup & Recreate"
|
|
2928
|
-
|
|
2929
|
-
2. **Via CLI:**
|
|
2930
|
-
```bash
|
|
2931
|
-
# Option 1: Manual cleanup
|
|
2932
|
-
rm -rf /path/to/project/workspaces/feature-issue-123
|
|
2933
|
-
pan workspace create ISSUE-123
|
|
2934
|
-
|
|
2935
|
-
# Option 2: Backup first
|
|
2936
|
-
cp -r /path/to/project/workspaces/feature-issue-123 /tmp/backup-issue-123
|
|
2937
|
-
rm -rf /path/to/project/workspaces/feature-issue-123
|
|
2938
|
-
pan workspace create ISSUE-123
|
|
2939
|
-
# Then manually restore files from backup
|
|
2940
|
-
```
|
|
2941
|
-
|
|
2942
|
-
**Prevention:**
|
|
2943
|
-
- Don't interrupt `pan workspace create` commands
|
|
2944
|
-
- Don't run `git worktree prune` in the main repo without checking for active workspaces
|
|
2945
|
-
- Ensure adequate disk space before creating workspaces
|
|
2946
|
-
|
|
2947
|
-
## ⭐ Star History
|
|
2948
|
-
|
|
2949
|
-
<a href="https://star-history.com/#eltmon/panopticon&Date">
|
|
2950
|
-
<picture>
|
|
2951
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=eltmon/panopticon&type=Date&theme=dark" />
|
|
2952
|
-
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=eltmon/panopticon&type=Date" />
|
|
2953
|
-
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=eltmon/panopticon&type=Date" />
|
|
2954
|
-
</picture>
|
|
2955
|
-
</a>
|
|
2956
|
-
|
|
2957
|
-
## ⚖️ License
|
|
2958
|
-
|
|
2959
|
-
This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
|
|
2960
|
-
|
|
2961
|
-
[](https://opensource.org/licenses/MIT)
|
|
347
|
+
<div align="center">
|
|
348
|
+
<p><strong>Made with ❤️ by the Panopticon team</strong></p>
|
|
349
|
+
<p><a href="https://github.com/eltmon/panopticon-cli">GitHub</a> · <a href="https://www.npmjs.com/package/panopticon-cli">npm</a> · <a href="docs/INDEX.md">Documentation</a></p>
|
|
350
|
+
</div>
|