h2pp — Telling h2's agents what to do

h2pp is a direction layer for h2, the agent runner, messaging, and orchestration tool.

h2 answers "how do I run agents?" — launching, managing, messaging, and multiplexing AI coding agents.

h2pp answers "what should they do?" — providing agents with structured work instructions via recipes and plans.

Status

h2pp is a bash proof-of-concept. The goal is to dogfood the recipe/plan workflow until it stabilizes, then port the functionality to Go as a PR to the h2 repository. If the PR is not accepted, h2pp may become a standalone tool.

The Problem

h2 is excellent at agent infrastructure but intentionally un-opinionated about what agents should work on. When you launch a pod of agents, they either sit idle or start improvising based on their role instructions. There's no built-in way to say "here's a specific job — execute it."

h2pp fills this gap with two concepts:

• Recipes — Reusable, refined workflow definitions stored as markdown files with YAML frontmatter. Designed to be run many times and improved over time. A recipe specifies which pod to use and gives the manager agent a structured brief to execute.
• Plans — Ad-hoc, one-time instructions, typically from Claude's ~/.claude/plans/ directory. Picked interactively and sent to a running pod's manager agent.

How It Works

# Launch a team of agents
h2pp start docs-update

# Open each agent in its own Ghostty tab
h2pp view

# Give them work
h2pp run update-site

# Or pick a Claude plan interactively
h2pp plan

# Check on progress
h2pp status

# Stop everything
h2pp stop

h2pp manages direction, not infrastructure. Under the hood it calls h2 pod launch, h2 send, h2 list, and h2 attach — composing h2's existing commands into a workflow.

Installation

# Clone the repo
git clone <repo-url> ~/Projects/h2pp

# Symlink to PATH
ln -sf ~/Projects/h2pp/h2pp /usr/local/bin/h2pp

# Install default roles, pods, and templates
h2pp init

# Set up shell completions
h2pp completion zsh

Requirements

• h2 — installed and initialized (h2 init --global)
• yq — for YAML parsing
• jq — for JSON processing (session management)
• Ghostty — terminal emulator (used for agent tab management)
• glow (optional) — for colorized markdown rendering in session views

Commands

Command	Description
h2pp init	Install default roles, pods, and templates to ~/.h2/
h2pp start <pod>	Launch a pod (agents wait for direction)
h2pp stop [<pod>]	Stop a pod (inferred if only one running)
h2pp restart [<pod>]	Restart a pod
h2pp view [<pod>]	Open each agent in its own Ghostty tab
h2pp watch [<pod>]	Split-pane monitor with agent switcher
h2pp attach <agent>	Attach to a specific agent
h2pp run <recipe>	Run a recipe (shorthand for recipe run)
h2pp recipe list	List available recipes (local + global)
h2pp recipe run <recipe>	Launch pod if needed and send recipe to manager
h2pp recipe show <recipe>	Display a recipe
h2pp recipe edit <recipe>	Edit a recipe in $EDITOR
h2pp recipe create <recipe>	Create a new recipe from template
h2pp plan [<pod>]	Pick a recent Claude plan and send to manager
h2pp plan [<pod>] <file>	Send a specific plan file to manager
h2pp tell <agent> <msg>	Send a message to a specific agent
h2pp session list	List recent sessions with status
h2pp session view <n>	View session summary (add -v for full messages, --less for pager)
h2pp session save	Save the most recent running session
h2pp session resolve	Resolve stale running sessions (also runs automatically in background)
h2pp session unlock	Remove a stuck session resolve lock
h2pp state list	List per-role state files
h2pp state show <role>	Display a role's state
h2pp state reset [<role>]	Clear state for a role (or all roles)
h2pp recommend list	List pending recipe recommendations
h2pp recommend show <pod>	Display recommendations for a pod
h2pp recommend resolve <pod>	Interactively review and apply recommendations
h2pp audit	Run documentation gap analysis script
h2pp status	Dashboard overview of running agents
h2pp list	Show running agents (passes through to h2 list)
h2pp completion <shell>	Write shell completions to ~/.h2/completions/

Recipes

Recipes are markdown files with YAML frontmatter, stored in two locations:

• Local: .h2/recipes/ (searched upward from $PWD) — project-specific recipes
• Global: ~/.h2/recipes/ — shared across all projects

Local recipes override global ones of the same name.

Recipe format

---
pod: docs-update
pod_vars:
  codename:
  working_dir: "."
  language: "Go"
  doc_framework: "Astro Starlight (MDX)"
---
# Update Documentation Site

## Goal

The documentation site should accurately reflect every component
package in this repo.

## Instructions

1. Audit current docs vs code
2. Update existing pages
3. Create missing pages
4. Verify site builds

## Constraints

- Do not modify source code
- Follow existing doc page patterns

## Criteria

- Site builds without errors
- Every package has a doc page
- No broken links

The frontmatter tells h2pp which pod template to launch and with what variables. The markdown body is sent to the pod's manager agent as the work brief. The ## Criteria section is parsed and sent separately as acceptance criteria for the evaluator.

Sessions

h2pp tracks recipe runs as sessions. Sessions capture agent messages and detect completion status (via exact markers or fuzzy natural-language matching).

Sessions are automatically resolved in the background on every h2pp invocation — stale "running" sessions are detected as completed/failed and optionally summarized via Claude CLI.

h2pp session list              # See all sessions with status
h2pp session view 1 -v         # Pretty-printed with glow-rendered messages
h2pp session view 1 -v --less  # Same, but piped through less

Pod Codenames

Pod templates use a codename variable to support multiple instances of the same template running simultaneously. h2pp derives the codename from the current directory name (e.g., go-tealeaves becomes tealeaves). This means you can run the same pod template for different projects at the same time:

# In ~/Projects/go-tealeaves/
h2pp start docs-update    # Creates pod: docs-update-tealeaves

# In ~/Projects/go-myapp/
h2pp start docs-update    # Creates pod: docs-update-myapp

Configuration

h2pp stores nothing of its own — it uses h2's existing configuration:

• Pod templates: ~/.h2/pods/*.yaml.tmpl
• Roles: ~/.h2/roles/*.yaml.tmpl
• Config: ~/.h2/config.yaml
• Completions: ~/.h2/completions/
• Recipes: ~/.h2/recipes/ (global) and .h2/recipes/ (per-project)
• Sessions: .h2/sessions/ (per-project)
• Recommendations: .h2/recommendations/ (per-project) and ~/.h2/recommendations/ (global)
• State: .h2/state/ (per-project)

Optional defaults in ~/.h2/config.yaml:

defaults:
  pod_vars:
    working_dir: "."

Project Structure

h2pp/
  h2pp                    # Main dispatcher (symlink target)
  lib/
    common.sh             # Config loading, pod helpers, recipe parsing
    ghostty.sh            # Ghostty tab management via JXA
    cmd-audit.sh          # Documentation gap analysis
    cmd-completion.sh     # Shell completion generation
    cmd-help.sh           # Usage text
    cmd-init.sh           # Install default roles/pods/templates
    cmd-plan.sh           # Claude plan picker
    cmd-recipe.sh         # Recipe CRUD and execution
    cmd-recommend.sh      # Manage recipe recommendations
    cmd-restart.sh        # Restart pods/agents
    cmd-session.sh        # Session capture, viewing, and resolution
    cmd-start.sh          # Launch pod
    cmd-state.sh          # Per-role state management
    cmd-status.sh         # Dashboard overview
    cmd-stop.sh           # Stop pod + close tabs
    cmd-tell.sh           # h2 send wrapper
    cmd-view.sh           # Open agent tabs in Ghostty
    cmd-watch.sh          # Split-pane monitor + agent switcher
  scripts/
    audit-docs.sh         # Go project documentation gap analysis
    h2pp-audit-docs       # Wrapper for audit script
  data/
    session-noise-patterns.yaml  # Message filtering patterns
  templates/
    recipes/              # Recipe templates
    pods/                 # Pod templates
    roles/                # Role templates
  docs/
    prompts/              # Research prompts for future h2 PRs

Relationship to h2

h2pp is designed to eventually merge into h2. Key design decisions reflect this:

• Zero h2pp footprint — no .h2pp directories or config files. Everything lives in h2's existing ~/.h2/ structure.
• Recipes extend h2's patterns — h2 has roles (how agents behave) and pods (which agents to launch). Recipes add the missing piece: what agents should do. Roles : behavior :: recipes : direction.
• Thin wrappers — most h2pp commands are thin compositions of existing h2 commands. The recipe system (h2 send manager "execute this brief") is the primary new functionality.

The PR positioning: recipes are to pods what pods are to individual agents — an optional, higher-level abstraction that formalizes a common pattern without forcing a workflow.

License

TBD