You are helping the user manage development projects with zp, a Zed project launcher that works across local macOS, Apple Containers, and Fly.io Sprites.
What zp Does
zp opens projects in Zed across three backends:
- local —
~/github/owner/nameon macOS - container — Apple Container (macOS 26+), projects at
/home/klundstedt/github/owner/name - sprite — Fly.io Sprite (remote VM), projects at
/home/klundstedt/github/owner/name
All backends use the ~/github/owner/name path convention. New machines are bootstrapped with dotfiles automatically.
Usage
zp [owner/name | name] [--backend local|container|sprite] [--machine <name>] [--org <org>]Non-Interactive Commands (Use These)
When calling zp programmatically, always provide all arguments to avoid TTY prompts:
# Open an existing project (fully specified)
zp owner/name --backend container --machine dev
# Create a new container, bootstrap it, clone repo, open in Zed
zp owner/name --backend container --machine new-machine-name
# Open locally
zp owner/name --backend local
# Open on a sprite
zp owner/name --backend sprite --machine myspriteWhen --machine names a machine that doesn't exist, zp creates it, bootstraps dotfiles, and clones the project — all non-interactively.
Interactive Commands (Require TTY)
These invoke fzf and are only usable when the user is at a terminal:
# Browse all projects across all backends
zp
# Search by repo name (fzf if multiple matches)
zp gitlake
# Search by owner/name (offers to clone if not found)
zp owner/name
# Browse projects on a specific backend
zp --backend container
zp --backend container --machine devBackends
Backends are plug-in shell scripts in ~/.local/bin/zp-backends/. Each implements:
| Function | Purpose |
|---|---|
backend_available | Check if CLI is installed |
backend_list | List machines |
backend_create <name> | Create a machine |
backend_start | Start/wake a machine |
backend_ensure_ssh | Set up SSH, return user@host[:port] |
backend_exec <cmd> | Run a command via native transport |
Common Agent Tasks
Open a project the user asks about
# Determine where it lives, then open it
zp owner/name --backend container --machine devCheck what projects exist on a machine
# List projects via backend_exec (no SSH needed)
container exec dev bash -c "find /home/klundstedt/github -mindepth 2 -maxdepth 2 -type d 2>/dev/null"Clone a new repo onto an existing machine
# zp handles clone automatically if the project doesn't exist on the target
zp owner/name --backend container --machine devCreate a fresh environment for a project
# New machine name → creates machine, bootstraps, clones, opens
zp owner/name --backend container --machine fresh-envAfter Opening a New Project
When zp clones a repo that doesn't have an AGENTS.md, suggest using the /bootstrap-project skill to set up agent context. This gives Claude Code and other agents the project-specific instructions they need to be effective.
Important Notes
- GitHub owner in the path (e.g.
kylelundstedt) is separate from the OS user (klundstedt). --backend local --machine Xis an error — local backend has no machines.- Stopped containers are started automatically. Sprites auto-wake on connection.
- Bootstrap runs
install.sh --no-promptfrom the dotfiles repo on new machines.