ppg — Pure Point Guard

A native macOS dashboard for orchestrating parallel AI coding agents.

Spawn, monitor, and merge multiple AI agents working in parallel — each isolated in its own git worktree. Watch them all from a single window.

Features

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.

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.

Agent-agnostic — Works with Claude Code, Codex, OpenCode, or any CLI agent. Define custom agents in config.

Git worktree isolation — Every agent works in its own worktree on its own branch. No file conflicts, clean merges.

Prompts editor — Write and manage reusable prompt templates with {{VAR}} substitution, right inside the app.

Swarms — Define multi-agent orchestrations in YAML. Choose shared or isolated strategies. Launch coordinated agent groups.

Project overview — Home dashboard shows all your projects with commit heatmaps, recent commits, agent status, and worktree counts at a glance.

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 (macOS app)

The dashboard is the primary interface. Download from GitHub Releases — grab the .dmg file.

Or install via CLI:

ppg install-dashboard

CLI (runtime engine)

The CLI is the engine that powers the dashboard. Install it globally:

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

# 1. Initialize ppg in your project
cd your-project
ppg init

# 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.

Or use the CLI directly

# 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

# Collect results
ppg aggregate --all

# Merge completed work
ppg merge wt-xxxxxx

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/
├── .ppg/
│   ├── config.yaml      # Agent and project config
│   ├── manifest.json     # Runtime state (worktrees, agents, status)
│   ├── templates/        # Reusable prompt templates
│   ├── prompts/          # Prompt files for swarms
│   └── results/          # Agent result files
├── .worktrees/
│   ├── wt-abc123/        # Isolated git worktree
│   └── wt-def456/        # Another worktree
└── ...

Agent lifecycle:

spawning → running → completed   (result file written)
                   → failed      (non-zero exit or shell prompt visible)
                   → killed      (via ppg kill)
                   → lost        (tmux pane died unexpectedly)

Configuration

.ppg/config.yaml:

sessionName: ppg
defaultAgent: claude

agents:
  claude:
    name: claude
    command: claude --dangerously-skip-permissions
    interactive: true
    resultInstructions: >-
      When you have completed the task, write a summary of what you did
      and any important notes to the file at: {{RESULT_FILE}}

  codex:
    name: codex
    command: codex
    promptFlag: --prompt
    interactive: true

  custom-script:
    name: custom
    command: ./scripts/my-agent.sh
    promptFlag: --task
    interactive: false

worktreeBase: .worktrees
templateDir: .ppg/templates
resultDir: .ppg/results
logDir: .ppg/logs
envFiles:
  - .env
  - .env.local
symlinkNodeModules: true

Templates

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: {{WORKTREE_PATH}}, {{BRANCH}}, {{AGENT_ID}}, {{RESULT_FILE}}, {{PROJECT_ROOT}}, {{TASK_NAME}}, {{PROMPT}}

Custom variables are passed with --var KEY=VALUE or defined in swarm YAML.

Global Prompts & Templates

Put prompts, templates, and swarms in ~/.ppg/ to make them available across all projects:

~/.ppg/
├── prompts/       # Global prompt files
├── templates/     # Global templates
└── swarms/        # Global swarm definitions

Project-local files always take precedence when names conflict. Use ppg list prompts or ppg list templates to see both local and global entries.

Cron Scheduling

Define recurring agent tasks in .ppg/schedules.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 * * * *'

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

Manage schedules visually from the Schedules tab in the dashboard.

CLI Reference

All commands support --json for machine-readable output.

| 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.

Conductor Mode

ppg is designed to be driven programmatically by a meta-agent (a "conductor"). All commands support --json for machine consumption.

# 1. Spawn agents
ppg spawn --name task-1 --prompt "Do X" --json
ppg spawn --name task-2 --prompt "Do Y" --json

# 2. Wait for completion
ppg wait --all --json

# 3. Aggregate results
ppg aggregate --all --json

# 4. Merge completed work
ppg merge wt-xxxxxx --json

Contributing

See CONTRIBUTING.md for development setup, testing, and code conventions.

License

MIT