panopticon-cli 0.4.5 → 0.4.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (169) hide show
  1. package/README.md +84 -2695
  2. package/dist/{agents-B5NRTVHK.js → agents-54LDKMHR.js} +8 -3
  3. package/dist/chunk-44EOY2ZL.js +58 -0
  4. package/dist/chunk-44EOY2ZL.js.map +1 -0
  5. package/dist/chunk-BWGFN44T.js +224 -0
  6. package/dist/chunk-BWGFN44T.js.map +1 -0
  7. package/dist/chunk-F7NQZD6H.js +49 -0
  8. package/dist/chunk-F7NQZD6H.js.map +1 -0
  9. package/dist/chunk-HCTJFIJJ.js +159 -0
  10. package/dist/chunk-HCTJFIJJ.js.map +1 -0
  11. package/dist/chunk-JM6V62LT.js +650 -0
  12. package/dist/chunk-JM6V62LT.js.map +1 -0
  13. package/dist/chunk-K45YD6A3.js +254 -0
  14. package/dist/chunk-K45YD6A3.js.map +1 -0
  15. package/dist/chunk-KGPRXDMX.js +137 -0
  16. package/dist/chunk-KGPRXDMX.js.map +1 -0
  17. package/dist/chunk-KQAEUOML.js +278 -0
  18. package/dist/chunk-KQAEUOML.js.map +1 -0
  19. package/dist/chunk-NYVQC3D7.js +90 -0
  20. package/dist/chunk-NYVQC3D7.js.map +1 -0
  21. package/dist/chunk-PUR532O7.js +1556 -0
  22. package/dist/chunk-PUR532O7.js.map +1 -0
  23. package/dist/chunk-VTDDVLCK.js +1977 -0
  24. package/dist/chunk-VTDDVLCK.js.map +1 -0
  25. package/dist/chunk-Z24TY3XN.js +916 -0
  26. package/dist/chunk-Z24TY3XN.js.map +1 -0
  27. package/dist/chunk-ZHC57RCV.js +44 -0
  28. package/dist/chunk-ZHC57RCV.js.map +1 -0
  29. package/dist/{chunk-ITI4IC5A.js → chunk-ZZ3477GY.js} +69 -100
  30. package/dist/chunk-ZZ3477GY.js.map +1 -0
  31. package/dist/cli/index.js +4664 -2912
  32. package/dist/cli/index.js.map +1 -1
  33. package/dist/dashboard/public/assets/index-CRqsEkmn.css +32 -0
  34. package/dist/dashboard/public/assets/index-DPSUbu4A.js +645 -0
  35. package/dist/dashboard/public/index.html +15 -3
  36. package/dist/dashboard/server.js +45663 -17860
  37. package/dist/dns-L3L2BB27.js +30 -0
  38. package/dist/dns-L3L2BB27.js.map +1 -0
  39. package/dist/index.d.ts +63 -3
  40. package/dist/index.js +42 -18
  41. package/dist/index.js.map +1 -1
  42. package/dist/projects-ESIB34QQ.js +43 -0
  43. package/dist/projects-ESIB34QQ.js.map +1 -0
  44. package/dist/remote-agents-Z3R2A5BN.js +25 -0
  45. package/dist/remote-agents-Z3R2A5BN.js.map +1 -0
  46. package/dist/remote-workspace-HI4VML6H.js +179 -0
  47. package/dist/remote-workspace-HI4VML6H.js.map +1 -0
  48. package/dist/specialist-context-SNCJ7O7G.js +256 -0
  49. package/dist/specialist-context-SNCJ7O7G.js.map +1 -0
  50. package/dist/specialist-logs-A7ODEK2T.js +43 -0
  51. package/dist/specialist-logs-A7ODEK2T.js.map +1 -0
  52. package/dist/specialists-C7XLNSXQ.js +121 -0
  53. package/dist/specialists-C7XLNSXQ.js.map +1 -0
  54. package/dist/traefik-WI3KSRGG.js +12 -0
  55. package/dist/traefik-WI3KSRGG.js.map +1 -0
  56. package/package.json +2 -1
  57. package/skills/beads/README.md +120 -0
  58. package/skills/beads/SKILL.md +214 -0
  59. package/skills/beads/adr/0001-bd-prime-as-source-of-truth.md +59 -0
  60. package/skills/beads/resources/AGENTS.md +62 -0
  61. package/skills/beads/resources/ASYNC_GATES.md +168 -0
  62. package/skills/beads/resources/BOUNDARIES.md +469 -0
  63. package/skills/beads/resources/CHEMISTRY_PATTERNS.md +197 -0
  64. package/skills/beads/resources/CLI_REFERENCE.md +558 -0
  65. package/skills/beads/resources/DEPENDENCIES.md +747 -0
  66. package/skills/beads/resources/INTEGRATION_PATTERNS.md +407 -0
  67. package/skills/beads/resources/ISSUE_CREATION.md +139 -0
  68. package/skills/beads/resources/MOLECULES.md +354 -0
  69. package/skills/beads/resources/PATTERNS.md +341 -0
  70. package/skills/beads/resources/RESUMABILITY.md +207 -0
  71. package/skills/beads/resources/STATIC_DATA.md +54 -0
  72. package/skills/beads/resources/TROUBLESHOOTING.md +489 -0
  73. package/skills/beads/resources/WORKFLOWS.md +623 -0
  74. package/skills/beads/resources/WORKTREES.md +94 -0
  75. package/skills/beads-completion-check/SKILL.md +90 -0
  76. package/skills/beads-panopticon-guide/SKILL.md +171 -0
  77. package/skills/bug-fix/SKILL.md +32 -0
  78. package/skills/clear-writing/SKILL.md +105 -0
  79. package/skills/clear-writing/references/elements-of-style/01-introductory.md +3 -0
  80. package/skills/clear-writing/references/elements-of-style/02-elementary-rules-of-usage.md +214 -0
  81. package/skills/clear-writing/references/elements-of-style/03-elementary-principles-of-composition.md +398 -0
  82. package/skills/clear-writing/references/elements-of-style/04-a-few-matters-of-form.md +89 -0
  83. package/skills/clear-writing/references/elements-of-style/05-words-and-expressions-commonly-misused.md +342 -0
  84. package/skills/clear-writing/references/signs-of-ai-writing.md +901 -0
  85. package/skills/code-review/SKILL.md +37 -0
  86. package/skills/code-review-performance/SKILL.md +53 -0
  87. package/skills/code-review-security/SKILL.md +35 -0
  88. package/skills/dependency-update/SKILL.md +30 -0
  89. package/skills/feature-work/SKILL.md +39 -0
  90. package/skills/incident-response/SKILL.md +32 -0
  91. package/skills/knowledge-capture/SKILL.md +463 -0
  92. package/skills/onboard-codebase/SKILL.md +34 -0
  93. package/skills/opus-plan/SKILL.md +400 -0
  94. package/skills/pan-approve/SKILL.md +136 -0
  95. package/skills/pan-code-review/SKILL.md +249 -0
  96. package/skills/pan-config/SKILL.md +164 -0
  97. package/skills/pan-convoy-synthesis/SKILL.md +249 -0
  98. package/skills/pan-diagnose/SKILL.md +360 -0
  99. package/skills/pan-docker/SKILL.md +279 -0
  100. package/skills/pan-docs/SKILL.md +113 -0
  101. package/skills/pan-down/SKILL.md +434 -0
  102. package/skills/pan-health/SKILL.md +240 -0
  103. package/skills/pan-help/SKILL.md +237 -0
  104. package/skills/pan-install/SKILL.md +339 -0
  105. package/skills/pan-issue/SKILL.md +596 -0
  106. package/skills/pan-kill/SKILL.md +172 -0
  107. package/skills/pan-logs/SKILL.md +255 -0
  108. package/skills/pan-network/SKILL.md +320 -0
  109. package/skills/pan-oversee/SKILL.md +290 -0
  110. package/skills/pan-plan/SKILL.md +521 -0
  111. package/skills/pan-projects/SKILL.md +239 -0
  112. package/skills/pan-quickstart/SKILL.md +440 -0
  113. package/skills/pan-reload/SKILL.md +44 -0
  114. package/skills/pan-rescue/SKILL.md +271 -0
  115. package/skills/pan-restart/SKILL.md +53 -0
  116. package/skills/pan-setup/SKILL.md +478 -0
  117. package/skills/pan-skill-creator/SKILL.md +168 -0
  118. package/skills/pan-skill-creator/references/output-patterns.md +141 -0
  119. package/skills/pan-skill-creator/references/workflows.md +90 -0
  120. package/skills/pan-skill-creator/scripts/init_skill.py +176 -0
  121. package/skills/pan-status/SKILL.md +493 -0
  122. package/skills/pan-subagent-creator/SKILL.md +295 -0
  123. package/skills/pan-subagent-creator/assets/validate-readonly-query.sh +35 -0
  124. package/skills/pan-subagent-creator/references/example-agents.md +308 -0
  125. package/skills/pan-subagent-creator/scripts/init_agent.py +126 -0
  126. package/skills/pan-sync/SKILL.md +272 -0
  127. package/skills/pan-tell/SKILL.md +157 -0
  128. package/skills/pan-test-config/SKILL.md +208 -0
  129. package/skills/pan-tracker/SKILL.md +288 -0
  130. package/skills/pan-up/SKILL.md +458 -0
  131. package/skills/pan-workspace-config/SKILL.md +303 -0
  132. package/skills/refactor/SKILL.md +30 -0
  133. package/skills/refactor-radar/SKILL.md +475 -0
  134. package/skills/release/SKILL.md +25 -0
  135. package/skills/send-feedback-to-agent/SKILL.md +98 -0
  136. package/skills/session-health/SKILL.md +76 -0
  137. package/skills/session-health/scripts/check_sessions.py +166 -0
  138. package/skills/skill-creator/SKILL.md +92 -0
  139. package/skills/skill-creator/scripts/init_skill.py +152 -0
  140. package/skills/skill-creator/scripts/package_skill.py +123 -0
  141. package/skills/stitch-design-md/README.md +34 -0
  142. package/skills/stitch-design-md/SKILL.md +172 -0
  143. package/skills/stitch-design-md/examples/DESIGN.md +154 -0
  144. package/skills/stitch-react-components/README.md +36 -0
  145. package/skills/stitch-react-components/SKILL.md +47 -0
  146. package/skills/stitch-react-components/examples/gold-standard-card.tsx +80 -0
  147. package/skills/stitch-react-components/package-lock.json +231 -0
  148. package/skills/stitch-react-components/package.json +16 -0
  149. package/skills/stitch-react-components/resources/architecture-checklist.md +15 -0
  150. package/skills/stitch-react-components/resources/component-template.tsx +37 -0
  151. package/skills/stitch-react-components/resources/stitch-api-reference.md +14 -0
  152. package/skills/stitch-react-components/resources/style-guide.json +27 -0
  153. package/skills/stitch-react-components/scripts/fetch-stitch.sh +30 -0
  154. package/skills/stitch-react-components/scripts/validate.js +68 -0
  155. package/skills/stitch-setup/SKILL.md +94 -0
  156. package/skills/web-design-guidelines/SKILL.md +39 -0
  157. package/skills/work-complete/SKILL.md +79 -0
  158. package/templates/traefik/docker-compose.yml +1 -1
  159. package/templates/traefik/dynamic/panopticon.yml.template +41 -0
  160. package/templates/traefik/traefik.yml +8 -0
  161. package/dist/chunk-7HHDVXBM.js +0 -349
  162. package/dist/chunk-7HHDVXBM.js.map +0 -1
  163. package/dist/chunk-H45CLB7E.js +0 -2044
  164. package/dist/chunk-H45CLB7E.js.map +0 -1
  165. package/dist/chunk-ITI4IC5A.js.map +0 -1
  166. package/dist/dashboard/public/assets/index-BDd8hGYb.css +0 -32
  167. package/dist/dashboard/public/assets/index-sFwLPko-.js +0 -556
  168. package/templates/traefik/dynamic/panopticon.yml +0 -51
  169. /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 installation guide, requirements, and platform support →](https://panopticon-cli.com/quickstart)**
209
+ 📖 **[Full documentation →](docs/INDEX.md)**
207
210
 
208
- ## Requirements
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
- - **ttyd** - Web terminal for interactive planning sessions. Auto-installed by `pan install`.
216
- - **GitHub CLI (`gh`)** - For GitHub integration (issues, PRs, merges). [Install](https://cli.github.com/)
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 integration
222
- - **Beads CLI (bd)** - For persistent task tracking across sessions. Auto-installed by `pan install`. Upgrade with `pan beads upgrade`.
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
- | Tracker | Role | Configuration |
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
- Secondary trackers sync issues to the dashboard alongside Linear issues, allowing unified project management.
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
- **Security:** For added security, restrict file permissions:
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
- # ~/.panopticon.env
333
- KIMI_API_KEY="sk-kimi-..."
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
- **Research-heavy workflows:**
369
- ```
370
- Research tasks → o3-deep-research (OpenAI)
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
- ### Register Projects
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
- ### How It Works
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
- When Stitch is configured, the planning agent can:
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
- - **Model Routing** - Routes tasks to appropriate models based on complexity
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
- ### How Cloister Works
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
- │ CLOISTER SERVICE │
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
- ### Starting Cloister
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
- ```bash
544
- # Via dashboard - click "Start" in the Cloister status bar
545
- # Or via CLI:
546
- pan cloister start
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
- # Check status
549
- pan cloister status
274
+ ### Multi-Agent Orchestration
275
+ Spawn and manage AI agents in tmux sessions, monitored by the Cloister lifecycle manager.
550
276
 
551
- # Stop monitoring
552
- pan cloister stop
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
- Cloister manages specialized agents that handle specific phases of the development lifecycle:
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
- 1. **Pull latest main** - Ensures local main is up-to-date
576
- 2. **Analyze incoming changes** - Reviews what the feature branch contains
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
- **Triggering merge-agent:**
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
- After a human initiates the first review, work-agents can request re-review up to 3 times automatically:
291
+ ## 🛠️ Common Commands
667
292
 
668
293
  ```bash
669
- # Work-agent requests re-review after fixing issues
670
- pan work request-review MIN-123 -m "Fixed: added tests for edge cases"
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
- ### Heartbeat Hook Installation
297
+ # Create workspace and spawn agent
298
+ pan workspace create PAN-123
768
299
 
769
- The heartbeat hook is automatically synced to `~/.panopticon/bin/heartbeat-hook` via `pan sync`. It's also installed automatically when you install or upgrade Panopticon via npm.
300
+ # Check agent status
301
+ pan status
770
302
 
771
- **Manual installation:**
772
- ```bash
773
- pan sync # Syncs all skills, agents, AND hooks
774
- ```
303
+ # View agent logs
304
+ pan logs agent-pan-123
775
305
 
776
- **Hook configuration in `~/.claude/settings.json`:**
777
- ```json
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
- **Hook resilience:** The heartbeat hook is designed to fail silently if:
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
- ## Model Routing & Complexity Detection
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
- **Keyword patterns:**
852
- ```javascript
853
- {
854
- trivial: ['typo', 'rename', 'comment', 'documentation', 'readme'],
855
- simple: ['add comment', 'update docs', 'fix typo', 'small fix'],
856
- medium: ['feature', 'endpoint', 'component', 'service'],
857
- complex: ['refactor', 'migration', 'redesign', 'overhaul'],
858
- expert: ['architecture', 'security', 'performance optimization']
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
- ## Multi-Project Support
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
- Panopticon creates workspaces as git worktrees. Docker, HTTPS, and seeding are opt-in.
331
+ Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
1183
332
 
1184
333
  ---
1185
334
 
1186
- ## Polyrepo Workspace Configuration
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
- **Solution:** Configure database seeding in `projects.yaml`:
337
+ [![Star History Chart](https://api.star-history.com/svg?repos=eltmon/panopticon-cli&type=Date)](https://star-history.com/#eltmon/panopticon-cli&Date)
1392
338
 
1393
- ```yaml
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
- # Command to create new snapshots from external source
1402
- snapshot_command: "kubectl exec -n prod pod/postgres -- pg_dump -U app mydb"
341
+ ## ⚖️ License
1403
342
 
1404
- # Or connect to external database directly
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
- # Container naming pattern
1412
- container_name: "{{PROJECT}}-postgres-1"
345
+ ---
1413
346
 
1414
- # Migration tool (for status checks)
1415
- migrations:
1416
- type: flyway # flyway | liquibase | prisma | typeorm | custom
1417
- path: src/main/resources/db/migration
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
- | ![Start](docs/planning-session-dialog.png) | ![Exploring](docs/planning-session-active.png) | ![Discovery](docs/planning-session-discovery.png) |
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
- ![Planning Session Output](docs/planning-session-output.png)
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
- ![Panopticon Dashboard](docs/dashboard-overview.png)
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
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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>