pure-point-guard 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-02-25
+
+### Added
+
+- **Global prompts, templates, and swarms** — `~/.ppg/` directory for cross-project reuse; project-local always takes precedence
+- **Cron scheduling** — `ppg cron start/stop/list/status` for recurring agent tasks via `.ppg/schedules.yaml`
+- **`ppg prompt` command** — sugar for `ppg spawn --prompt-file .ppg/prompts/<name>.md`
+- **`ppg list prompts`** — list available prompt files with variables and source (local/global)
+- **Schedules dashboard tab** — manage cron schedules with YAML editor, daemon start/stop, and new schedule dialog
+- **Global entries in dashboard** — Prompts and Swarms views show `~/.ppg/` entries marked as "Global"
+
+### Changed
+
+- **Config directory renamed** — `.pg/` → `.ppg/` to match the CLI name
+- **Internal symbols renamed** — `PgError` → `PpgError`, `pgDir()` → `ppgDir()`
+
 ## [0.2.0] - 2026-02-25
 
 ### Added
@@ -65,6 +81,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Status detection via signal-stack: result file, pane existence, pane liveness, current command
 - Native macOS dashboard app (`ppg ui`)
 
+[0.3.0]: https://github.com/2witstudios/ppg-cli/releases/tag/v0.3.0
 [0.2.0]: https://github.com/2witstudios/ppg-cli/releases/tag/v0.2.0
 [0.1.1]: https://github.com/2witstudios/ppg-cli/releases/tag/v0.1.1
 [0.1.0]: https://github.com/2witstudios/ppg-cli/releases/tag/v0.1.0

package/README.md

@@ -4,92 +4,106 @@
 [![npm version](https://img.shields.io/npm/v/pure-point-guard.svg)](https://www.npmjs.com/package/pure-point-guard)
 [![license](https://img.shields.io/npm/l/pure-point-guard.svg)](https://github.com/2witstudios/ppg-cli/blob/main/LICENSE)
 
-Local orchestration runtime for parallel CLI coding agents.
+A native macOS dashboard for orchestrating parallel AI coding agents.
 
-ppg spawns multiple AI coding agents in isolated git worktrees, each in its own tmux pane, and gives you a single control plane to monitor, aggregate, and merge their work.
+Spawn, monitor, and merge multiple AI agents working in parallel — each isolated in its own git worktree. Watch them all from a single window.
 
-## Why
+![ppg dashboard](screenshot.png)
 
-When you have a large task — adding tests across a codebase, refactoring multiple modules, fixing a batch of issues — you can break it into independent units and run them in parallel. ppg handles the plumbing: worktree creation, agent spawning, tmux session management, status tracking, result collection, and branch merging.
+## Features
 
-It works with any CLI agent (Claude Code, Codex, custom scripts) and is designed to be driven by a human or by a "conductor" meta-agent.
+**Multi-agent dashboard** — See all your projects, worktrees, and agents in one place. Each agent gets a live terminal pane so you can watch it work in real time.
 
-## Requirements
+**Command palette** — Hit a key to spawn a new agent (Claude, Codex, OpenCode), open a terminal, or create a worktree. Type a prompt and it's running in seconds.
 
-- **Node.js** >= 20
-- **git** (with worktree support)
-- **tmux** (`brew install tmux`)
-- **macOS** (Terminal.app auto-open uses AppleScript; tmux features work anywhere)
+**Agent-agnostic** — Works with Claude Code, Codex, OpenCode, or any CLI agent. Define custom agents in config.
 
-## Install
+**Git worktree isolation** — Every agent works in its own worktree on its own branch. No file conflicts, clean merges.
 
-### CLI
+**Prompts editor** — Write and manage reusable prompt templates with `{{VAR}}` substitution, right inside the app.
 
-```bash
-npm install -g pure-point-guard
-```
+**Swarms** — Define multi-agent orchestrations in YAML. Choose shared or isolated strategies. Launch coordinated agent groups.
 
-### Claude Code Integration
+**Project overview** — Home dashboard shows all your projects with commit heatmaps, recent commits, agent status, and worktree counts at a glance.
 
-Running `ppg init` in any project automatically installs the `/ppg` skill for Claude Code. This gives Claude the ability to orchestrate parallel agents — just type `/ppg` in any Claude Code session.
+**Inline rename** — Click any agent, terminal, or worktree name in the sidebar to rename it.
+
+**Split panes** — Run multiple agents in the same worktree with split terminal views.
+
+**Cron scheduling** — Define recurring agent tasks in `.ppg/schedules.yaml`. The daemon triggers swarms or prompts on cron expressions. Manage from the Schedules dashboard tab or `ppg cron` CLI.
+
+**Global prompts & templates** — Put prompts, templates, and swarms in `~/.ppg/` to share them across all projects. Project-local always takes precedence.
+
+**Customizable** — Appearance modes (light/dark/system), terminal font and size, keybinding customization, configurable shell.
+
+## Install
 
-### Dashboard (optional)
+### Dashboard (macOS app)
 
-The native macOS dashboard app provides a visual interface for monitoring agents and worktrees.
+The dashboard is the primary interface. Download from [GitHub Releases](https://github.com/2witstudios/ppg-cli/releases/latest) — grab the `.dmg` file.
 
-**Via CLI:**
+Or install via CLI:
 
 ```bash
 ppg install-dashboard
 ```
 
-**Or download directly** from [GitHub Releases](https://github.com/2witstudios/ppg-cli/releases/latest) — grab the `.dmg` file.
+### CLI (runtime engine)
+
+The CLI is the engine that powers the dashboard. Install it globally:
+
+```bash
+npm install -g pure-point-guard
+```
+
+**Requirements:** Node.js >= 20, git, tmux (`brew install tmux`), macOS
+
+### Claude Code integration
+
+Running `ppg init` in any project automatically installs the `/ppg` skill for Claude Code. This gives Claude the ability to orchestrate parallel agents — just type `/ppg` in any Claude Code session.
 
 ## Quick Start
 
 ```bash
-# Initialize in your project
+# 1. Initialize ppg in your project
 cd your-project
 ppg init
 
-# Spawn an agent
-ppg spawn --name fix-auth --prompt "Fix the authentication bug in src/auth.ts"
+# 2. Open the dashboard
+ppg ui
+```
+
+From the dashboard, use the command palette to spawn agents, watch their progress in real time, and merge completed work.
 
-# Spawn multiple agents in parallel
+### Or use the CLI directly
+
+```bash
+# Spawn agents
+ppg spawn --name fix-auth --prompt "Fix the authentication bug in src/auth.ts"
 ppg spawn --name add-tests --prompt "Add unit tests for src/utils/"
 ppg spawn --name update-docs --prompt "Update the API documentation"
 
 # Check status
 ppg status
 
-# Watch status live
-ppg status --watch
-
-# View agent output
-ppg logs ag-xxxxxxxx
-
 # Collect results
 ppg aggregate --all
 
-# Merge a completed worktree back
+# Merge completed work
 ppg merge wt-xxxxxx
-
-# Open the dashboard
-ppg ui
 ```
 
-Each `ppg spawn` creates a git worktree, opens a tmux pane, launches the agent, and pops open a Terminal.app window so you can watch it work.
-
 ## How It Works
 
+Each `ppg spawn` creates a git worktree on a `ppg/<name>` branch, opens a tmux pane, and launches the agent. The dashboard watches the manifest file in real time — no IPC, no server.
+
 ```
 your-project/
-├── .pg/
+├── .ppg/
 │   ├── config.yaml      # Agent and project config
 │   ├── manifest.json     # Runtime state (worktrees, agents, status)
 │   ├── templates/        # Reusable prompt templates
-│   ├── prompts/          # Reusable prompt files for swarms
-│   ├── agent-prompts/    # Rendered per-agent prompt files (ephemeral)
+│   ├── prompts/          # Prompt files for swarms
 │   └── results/          # Agent result files
 ├── .worktrees/
 │   ├── wt-abc123/        # Isolated git worktree
@@ -97,214 +111,18 @@ your-project/
 └── ...
 ```
 
-**Worktrees** are isolated git checkouts on their own branches (`ppg/<name>`). Each agent works in its own worktree so there are no file conflicts between parallel agents.
-
-**tmux** provides the process management layer. One session per project, one window per worktree, one pane per agent. This gives you `ppg logs`, `ppg status`, `ppg attach`, and `ppg kill` for free.
-
-**Terminal.app windows** open automatically when agents spawn (macOS), so you can see what every agent is doing without manually attaching. Use `--no-open` to suppress this.
-
-## Commands
-
-### `ppg init`
-
-Initialize ppg in the current git repository. Creates `.pg/` directory with default config and a sample template. Also installs the `/ppg` Claude Code skill if Claude Code is available.
-
-```bash
-ppg init
-ppg init --json
-```
-
-### `ppg spawn`
-
-Spawn a new worktree with agent(s), or add agents to an existing worktree.
-
-```bash
-# Inline prompt
-ppg spawn --name fix-bug --prompt "Fix the null check in parser.ts"
-
-# From a file
-ppg spawn --name refactor --prompt-file tasks/refactor-auth.md
-
-# Using a template with variables
-ppg spawn --name add-tests --template test-writer --var SCOPE=auth --var STYLE=unit
-
-# Multiple agents in one worktree
-ppg spawn --name big-task --prompt "Implement feature X" --count 2
-
-# Split panes in one window
-ppg spawn --name big-task --prompt "Implement feature X" --count 2 --split
-
-# Add agent to existing worktree
-ppg spawn --worktree wt-abc123 --prompt "Review the changes"
-
-# Silent mode (no Terminal window)
-ppg spawn --name ci-task --prompt "Run linting" --no-open
-
-# Specify base branch
-ppg spawn --name hotfix --prompt "Fix critical bug" --base release/v2
-```
-
-| Option | Description |
-|---|---|
-| `-n, --name <name>` | Name for the worktree (becomes branch `ppg/<name>`) |
-| `-a, --agent <type>` | Agent type from config (default: `claude`) |
-| `-p, --prompt <text>` | Inline prompt text |
-| `-f, --prompt-file <path>` | Read prompt from file |
-| `-t, --template <name>` | Use a template from `.pg/templates/` |
-| `--var <key=value>` | Template variable (repeatable) |
-| `-b, --base <branch>` | Base branch for the worktree |
-| `-w, --worktree <id>` | Add agent to existing worktree instead of creating new |
-| `-c, --count <n>` | Number of agents to spawn (default: 1) |
-| `--split` | Put all agents in one window as split panes |
-| `--no-open` | Don't open a Terminal window |
-| `--json` | JSON output |
-
-### `ppg status`
-
-Show status of all worktrees and agents.
-
-```bash
-ppg status              # Pretty table
-ppg status --json       # Machine-readable
-ppg status --watch      # Live updates
-ppg status my-task      # Filter by worktree name
-```
-
-### `ppg attach`
-
-Open a terminal attached to a worktree or agent pane. If you're already in tmux, it switches to the target pane. Otherwise it opens a new Terminal.app window.
-
-```bash
-ppg attach wt-abc123    # By worktree ID
-ppg attach my-task      # By worktree name
-ppg attach ag-xxxxxxxx  # By agent ID
-```
-
-### `ppg logs`
-
-View captured output from an agent's tmux pane.
-
-```bash
-ppg logs ag-xxxxxxxx              # Last 100 lines
-ppg logs ag-xxxxxxxx --lines 500  # Last 500 lines
-ppg logs ag-xxxxxxxx --follow     # Tail (polls every 1s)
-ppg logs ag-xxxxxxxx --full       # Full pane history
-```
-
-### `ppg kill`
-
-Kill agents and optionally remove worktrees.
-
-```bash
-ppg kill --agent ag-xxxxxxxx       # Kill one agent
-ppg kill --worktree wt-abc123      # Kill all agents in worktree
-ppg kill --all                     # Kill everything
-ppg kill --all --remove            # Kill everything and remove worktrees
-```
-
-### `ppg aggregate`
-
-Collect result files from completed agents.
-
-```bash
-ppg aggregate wt-abc123            # Results from one worktree
-ppg aggregate --all                # Results from all worktrees
-ppg aggregate --all -o results.md  # Write to file
-```
-
-### `ppg merge`
-
-Merge a worktree branch back into its base branch.
-
-```bash
-ppg merge wt-abc123                # Squash merge (default)
-ppg merge wt-abc123 -s no-ff      # No-ff merge
-ppg merge wt-abc123 --dry-run     # Preview
-ppg merge wt-abc123 --no-cleanup  # Keep worktree after merge
-ppg merge wt-abc123 --force       # Merge even if agents aren't done
-```
-
-### `ppg diff`
-
-Show changes made in a worktree branch relative to its base.
-
-```bash
-ppg diff wt-abc123                 # Full diff
-ppg diff wt-abc123 --stat          # Diffstat summary
-ppg diff wt-abc123 --name-only     # Changed file names only
-```
-
-### `ppg restart`
-
-Restart a failed or killed agent in the same worktree.
-
-```bash
-ppg restart ag-xxxxxxxx                        # Restart with original prompt
-ppg restart ag-xxxxxxxx --prompt "Try again"   # Override the prompt
-ppg restart ag-xxxxxxxx --agent codex          # Override the agent type
-```
-
-### `ppg send`
-
-Send text or keystrokes to an agent's tmux pane.
-
-```bash
-ppg send ag-xxxxxxxx "yes"          # Send text + Enter
-ppg send ag-xxxxxxxx "y" --no-enter # Send text without Enter
-ppg send ag-xxxxxxxx "C-c" --keys   # Send raw tmux key names
-```
-
-### `ppg wait`
-
-Wait for agents to reach a terminal state (completed, failed, killed, lost).
-
-```bash
-ppg wait wt-abc123                    # Wait for all agents in worktree
-ppg wait --all                        # Wait for all agents everywhere
-ppg wait --all --timeout 300          # Timeout after 5 minutes
-ppg wait --all --interval 10          # Poll every 10 seconds
-```
-
-### `ppg clean`
+**Agent lifecycle:**
 
-Remove worktrees in terminal states (merged, cleaned, failed).
-
-```bash
-ppg clean                    # Clean merged/cleaned worktrees
-ppg clean --all              # Also clean failed worktrees
-ppg clean --dry-run          # Preview what would be cleaned
-ppg clean --prune            # Also run git worktree prune
 ```
-
-### `ppg worktree create`
-
-Create a standalone worktree without spawning any agents.
-
-```bash
-ppg worktree create --name my-branch
-ppg worktree create --name my-branch --base develop
-```
-
-### `ppg list templates`
-
-List available prompt templates from `.pg/templates/`.
-
-### `ppg install-dashboard`
-
-Download and install the native macOS dashboard app from GitHub Releases.
-
-```bash
-ppg install-dashboard                    # Install to /Applications
-ppg install-dashboard --dir ~/Apps       # Custom install directory
+spawning → running → completed   (result file written)
+                   → failed      (non-zero exit or shell prompt visible)
+                   → killed      (via ppg kill)
+                   → lost        (tmux pane died unexpectedly)
 ```
 
-### `ppg ui`
-
-Open the native macOS dashboard app (alias: `ppg dashboard`).
-
 ## Configuration
 
-`.pg/config.yaml`:
+`.ppg/config.yaml`:
 
 ```yaml
 sessionName: ppg
@@ -319,27 +137,6 @@ agents:
       When you have completed the task, write a summary of what you did
       and any important notes to the file at: {{RESULT_FILE}}
 
-worktreeBase: .worktrees
-templateDir: .pg/templates
-resultDir: .pg/results
-logDir: .pg/logs
-envFiles:
-  - .env
-  - .env.local
-symlinkNodeModules: true
-```
-
-### Custom Agents
-
-Add any CLI agent by defining it in the agents map:
-
-```yaml
-agents:
-  claude:
-    name: claude
-    command: claude --dangerously-skip-permissions
-    interactive: true
-
   codex:
     name: codex
     command: codex
@@ -351,109 +148,114 @@ agents:
     command: ./scripts/my-agent.sh
     promptFlag: --task
     interactive: false
-```
 
-Then spawn with `ppg spawn --agent codex --prompt "..."`.
+worktreeBase: .worktrees
+templateDir: .ppg/templates
+resultDir: .ppg/results
+logDir: .ppg/logs
+envFiles:
+  - .env
+  - .env.local
+symlinkNodeModules: true
+```
 
 ## Templates
 
-Templates live in `.pg/templates/` as Markdown files with `{{VAR}}` placeholders.
+Templates live in `.ppg/templates/` as Markdown files with `{{VAR}}` placeholders. The prompts editor in the dashboard lets you create and edit these visually.
 
-**Built-in variables:**
+**Built-in variables:** `{{WORKTREE_PATH}}`, `{{BRANCH}}`, `{{AGENT_ID}}`, `{{RESULT_FILE}}`, `{{PROJECT_ROOT}}`, `{{TASK_NAME}}`, `{{PROMPT}}`
 
-| Variable | Value |
-|---|---|
-| `{{WORKTREE_PATH}}` | Path to the agent's worktree |
-| `{{BRANCH}}` | Git branch name |
-| `{{AGENT_ID}}` | Agent identifier |
-| `{{RESULT_FILE}}` | Where the agent should write results |
-| `{{PROJECT_ROOT}}` | Repository root path |
-| `{{TASK_NAME}}` | Worktree name |
-| `{{PROMPT}}` | The prompt text |
+Custom variables are passed with `--var KEY=VALUE` or defined in swarm YAML.
+
+## Global Prompts & Templates
 
-Custom variables are passed with `--var KEY=VALUE`.
+Put prompts, templates, and swarms in `~/.ppg/` to make them available across all projects:
 
-**Example template** (`.pg/templates/test-writer.md`):
+```
+~/.ppg/
+├── prompts/       # Global prompt files
+├── templates/     # Global templates
+└── swarms/        # Global swarm definitions
+```
 
-```markdown
-# Task: {{TASK_NAME}}
+Project-local files always take precedence when names conflict. Use `ppg list prompts` or `ppg list templates` to see both local and global entries.
 
-Write comprehensive tests for the {{SCOPE}} module.
+## Cron Scheduling
 
-## Working Directory
-{{WORKTREE_PATH}}
+Define recurring agent tasks in `.ppg/schedules.yaml`:
 
-## Guidelines
-- Use {{FRAMEWORK}} for test framework
-- Aim for >90% coverage
-- Write your summary to {{RESULT_FILE}} when done
+```yaml
+schedules:
+  - name: nightly-review
+    swarm: code-review
+    cron: '0 2 * * *'
+    vars:
+      CONTEXT: 'Review all changes from the last 24 hours'
+  - name: hourly-lint
+    prompt: lint-check
+    cron: '0 * * * *'
 ```
 
 ```bash
-ppg spawn --name auth-tests --template test-writer --var SCOPE=auth --var FRAMEWORK=vitest
+ppg cron start    # Start the scheduler daemon
+ppg cron list     # Show schedules with next run times
+ppg cron status   # Check daemon status
+ppg cron stop     # Stop the daemon
 ```
 
-## Agent Lifecycle
+Manage schedules visually from the Schedules tab in the dashboard.
 
-```
-spawning → running → completed   (result file written)
-                   → failed      (non-zero exit or shell prompt visible)
-                   → killed      (via ppg kill)
-                   → lost        (tmux pane died unexpectedly)
-```
+## CLI Reference
 
-Status is determined by checking (in order):
-1. Result file exists → `completed`
-2. Tmux pane gone → `lost`
-3. Pane dead with exit 0 → `completed`
-4. Pane dead with non-zero exit → `failed`
-5. Pane alive, shell prompt visible → `failed` (agent exited without writing results)
-6. Otherwise → `running`
+All commands support `--json` for machine-readable output.
 
-## Conductor Mode
+| Command | Description |
+|---|---|
+| `ppg init` | Initialize ppg in the current git repo |
+| `ppg spawn` | Spawn a worktree with agent(s) |
+| `ppg status` | Show status of all worktrees and agents |
+| `ppg attach` | Open a terminal attached to a worktree or agent |
+| `ppg logs` | View agent output from tmux pane |
+| `ppg kill` | Kill agents and optionally remove worktrees |
+| `ppg aggregate` | Collect result files from completed agents |
+| `ppg merge` | Merge a worktree branch back into base |
+| `ppg diff` | Show changes in a worktree branch |
+| `ppg restart` | Restart a failed or killed agent |
+| `ppg send` | Send text or keystrokes to an agent pane |
+| `ppg wait` | Wait for agents to complete |
+| `ppg clean` | Remove worktrees in terminal states |
+| `ppg worktree create` | Create a standalone worktree |
+| `ppg list templates` | List available prompt templates |
+| `ppg list prompts` | List available prompt files |
+| `ppg prompt` | Spawn an agent from a prompt file |
+| `ppg cron start` | Start the cron scheduler daemon |
+| `ppg cron stop` | Stop the cron scheduler daemon |
+| `ppg cron list` | Show configured schedules with next run times |
+| `ppg cron status` | Show daemon status and recent log entries |
+| `ppg install-dashboard` | Download and install the macOS dashboard |
+| `ppg ui` | Open the dashboard |
+
+Run `ppg <command> --help` for detailed options.
 
-ppg is designed to be driven programmatically by a meta-agent (a "conductor"). All orchestration commands (`spawn`, `status`, `kill`, `wait`, `aggregate`, `merge`) support `--json` for machine-readable output.
+## Conductor Mode
 
-**Conductor workflow:**
+ppg is designed to be driven programmatically by a meta-agent (a "conductor"). All commands support `--json` for machine consumption.
 
 ```bash
-# 1. Plan — break the task into independent units
-# 2. Spawn agents
+# 1. Spawn agents
 ppg spawn --name task-1 --prompt "Do X" --json
 ppg spawn --name task-2 --prompt "Do Y" --json
 
-# 3. Poll for completion
-ppg status --json   # check for status: "completed" or "failed"
-
-# 4. Wait for all agents
+# 2. Wait for completion
 ppg wait --all --json
 
-# 5. Aggregate results
+# 3. Aggregate results
 ppg aggregate --all --json
 
-# 6. Merge completed work
+# 4. Merge completed work
 ppg merge wt-xxxxxx --json
 ```
 
-Key principles:
-- Always use `--json` for machine-readable output
-- Poll status every 5 seconds or use `ppg wait`
-- One concern per worktree for clean merges
-- Use `ppg aggregate` to collect and review results before merging
-
-## Architecture
-
-```
-src/
-├── cli.ts              # Entry point — registers commands with Commander.js
-├── commands/           # Command implementations
-├── core/               # Domain logic (manifest, agent, worktree, tmux, terminal, config)
-├── lib/                # Utilities (paths, errors, id, output, shell)
-└── types/              # Type definitions
-```
-
-Built with TypeScript (strict, ES2022, ESM-only), Commander.js for CLI framework, and tmux + git worktrees as foundational abstractions. See [CONTRIBUTING.md](CONTRIBUTING.md) for development details.
-
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and code conventions.