diff --git a/.agents/docs/demo-gif-creation.md b/.agents/docs/demo-gif-creation.md new file mode 100644 index 0000000..6e07b28 --- /dev/null +++ b/.agents/docs/demo-gif-creation.md @@ -0,0 +1,65 @@ +# Demo GIF creation + +Source-of-truth process for the `docs/public/demo.gif` shown in the README and used in Show HN / social-media posts. + +## Why manual, not CI + +We considered a GitHub Action that re-renders `demo.gif` whenever `packages/cli/src/**` changes. Rejected for HN launch: it adds a moving part to the repo before the launch story is settled, and stale screenshots rarely block users more than a 5-minute manual re-render. Reconsider in v0.6.x if the GIF goes stale visibly more than twice. + +## Tool + +[VHS](https://github.com/charmbracelet/vhs) — declarative `.tape` files, real pixel output, regenerable by anyone with VHS installed. [gum](https://github.com/charmbracelet/gum) drives the fake-agent HUD (Frame 3). + +```bash +mise install # picks up vhs + aqua:charmbracelet/gum from mise.toml +``` + +## Files + +``` +docs/public/demo.tape # source of truth (declarative script) +docs/public/demo-agent-hud.sh # scripted fake-agent HUD (gum banner/spinner/tool-call lines) +docs/public/demo.gif # rendered artifact (committed, referenced in README) +docs/public/demo.mp4 # rendered artifact (committed, for social posts) +``` + +## Render locally + +```bash +cd docs/public +vhs demo.tape # produces demo.gif + demo.mp4 +``` + +Re-render whenever any of these change: + +- The CLI's `add` command output (installer text) +- The Tier-1 harness list (Claude Code, Codex, OpenCode, Pi) +- The plugin name featured in the storyboard (`agentplugins-conventional-commits`) + +## Storyboard (current) + +| Frame | Duration | What happens | +| --- | --- | --- | +| 1 | 0–1s | `cd` into a pre-warmed demo folder | +| 2 | 1–2s | User's natural-language ask typed live (shell comment, cosmetic only) | +| 3 | 2–6s | Scripted fake-agent HUD runs (`docs/public/demo-agent-hud.sh`), prints `Plugin is ready` | +| 4 | 6–7s | `clear` | +| 5 | 7–12s | Real `agentplugins add sigilco/agentplugins-conventional-commits -y`, waits for `Installed to:` (the punchline) | + +Total budget: 15–30s, width 1200, height 700, font size 18. + +## Agent HUD (Frame 3) — why scripted + +A live capture of the agent scaffolding the plugin is more authentic, but brittle and slow: any agent behavior change breaks the tape, and a real `claude` run takes 5–15 minutes to render. Instead `docs/public/demo-agent-hud.sh` drives [`gum`](https://github.com/charmbracelet/gum) (mise tool `aqua:charmbracelet/gum`) to render a real bordered banner, a real animated spinner, and boxed tool-call lines — deterministic, no network/API calls, runs in ~3s. The install segment stays a real, live `agentplugins add` call; it's already fast and deterministic, and is the visual punchline. + +## Plumbing + +- VHS pulls `ttyd` and `ffmpeg` automatically on macOS. +- The `.tape` uses `Output docs/public/demo.gif` and `Output docs/public/demo.mp4` so a single run produces both. +- Screenshots reference `./docs/public/img/logo-light.png` and `./docs/public/img/logo-dark.png` if any frame embeds the logo. + +## What is NOT in scope + +- Auto-rendering on PR / CLI change (deferred to v0.6.x). +- GIF hosting on a CDN (the file is small and GitHub renders it natively). +- git-lfs (the GIF stays under 5 MB; if it ever blows past, switch then). \ No newline at end of file diff --git a/.gitignore b/.gitignore index 4fb4f63..6a66c5c 100644 --- a/.gitignore +++ b/.gitignore @@ -59,6 +59,9 @@ docs/public/* !docs/public/img/ !docs/public/img/logo-dark.png !docs/public/img/logo-light.png +!docs/public/demo.tape +!docs/public/demo.gif +!docs/public/demo.mp4 # Misc *.local diff --git a/README.md b/README.md index 7d3c62f..6d51795 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,67 @@ -# AgentPlugins - -

+

AgentPlugins

-> Write AI agent plugins once, ship to any harness. +

AgentPlugins

+ +

+ Write AI agent plugins once, ship to any harness. +

+ +

+ License + npm version + npm downloads + CI + Sponsor +

+ +## Why + +- **Write once, run everywhere** — one manifest compiles to Claude Code, Codex, OpenCode, Pi Mono, Copilot, Gemini, and Kimi +- **Universal codegen first, per-harness fallback second** — Tier-1 harnesses get full parity; Tier-2 gets skills + commands + a subset of hooks +- **No runtime proxy** — every adapter emits the harness's native output format; no shim layer, no lock-in +- **Honest capability matrix** — capability gaps emit `WARN` at compile time and surface on the [capability matrix page](https://agentplugins.pages.dev/guide/capability-matrix) +- **Plays nicely with what you already have** — install a plugin into a harness that already has its own plugins; they coexist -Install any plugin into every supported AI agent — **Tier-1:** Claude Code, Codex, OpenCode, Pi Mono. **Tier-2:** Copilot, Gemini, Kimi. +## Install -[**Sponsor development →**](https://buy.polar.sh/polar_cl_Mv1gdlG7bw3I70EC9IHtfeSHJj4PEKvA7JAUz23CFhj) +Install the CLI, then add any plugin to every supported AI agent — **Tier-1:** Claude Code, Codex, OpenCode, Pi Mono. **Tier-2:** Copilot, Gemini, Kimi. ```bash -npx @agentplugins/cli add user/awesome-plugin +curl -fsSL https://agentplugins.pages.dev/install.sh | bash +agentplugins add user/awesome-plugin ``` +Or skip the install and use `npx`: + ```bash -agentplugins add sigilco/agentplugins-ponytail +npx @agentplugins/cli add user/awesome-plugin ``` -Or install the CLI globally first: +Full guide → [agentplugins.pages.dev/guide/install](https://agentplugins.pages.dev/guide/install) + +

+ AgentPlugins demo: build once, install everywhere +

+ +## Quick start + +From zero to a working plugin in any supported harness: ```bash -curl -fsSL https://agentplugins.pages.dev/install.sh | bash +# Scaffold a new plugin from the official template +npx @agentplugins/cli init my-plugin +cd my-plugin + +# Install it into every supported harness (writes to ~/.claude, ~/.codex, etc.) +npx @agentplugins/cli add . + +# Verify the install landed where you expect +npx @agentplugins/cli doctor ``` ## Create a plugin @@ -60,6 +97,10 @@ Full docs → [agentplugins.pages.dev](https://agentplugins.pages.dev) LLMs.txt for AI agents → [agentplugins.pages.dev/llms.txt](https://agentplugins.pages.dev/llms.txt) +## Contributing + +PRs welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md), file issues, and join the conversation in [Discussions](https://github.com/sigilco/agentplugins/discussions). + --- Apache-2.0 · [GitHub](https://github.com/sigilco/agentplugins) · [Sponsor](https://buy.polar.sh/polar_cl_Mv1gdlG7bw3I70EC9IHtfeSHJj4PEKvA7JAUz23CFhj) diff --git a/docs/public/demo.gif b/docs/public/demo.gif new file mode 100644 index 0000000..8ebe6a5 Binary files /dev/null and b/docs/public/demo.gif differ diff --git a/docs/public/demo.mp4 b/docs/public/demo.mp4 new file mode 100644 index 0000000..a2ebb64 Binary files /dev/null and b/docs/public/demo.mp4 differ diff --git a/docs/public/demo.tape b/docs/public/demo.tape new file mode 100644 index 0000000..b1f13a9 --- /dev/null +++ b/docs/public/demo.tape @@ -0,0 +1,83 @@ +# AgentPlugins demo GIF — VHS source of truth (scripted fake-agent HUD + real install) +# +# Render: vhs docs/public/demo.tape +# Produces: docs/public/demo.gif + docs/public/demo.mp4 (canonical, <5 MB) +# +# Higher-res render for social media: render with docs/public/demo-hq.tape at +# 1920x1080 — see .agents/docs/demo-gif-creation.md. +# +# This tape types a natural prompt live (real VHS typing animation), then runs +# a scripted fake-agent HUD (docs/public/demo-agent-hud.sh, gum-driven: real +# bordered banner + real animated spinner + boxed tool-call lines) that prints +# `Plugin is ready` deterministically in ~3s — no live `claude` call, no +# network, no flakiness. The install segment (`agentplugins add ...`) is real +# and is the visual punchline; it runs with HOME pointed at a throwaway /tmp +# dir so the printed install paths and on-disk writes don't leak the +# operator's real home directory/username into a publicly shared asset. +# +# Fallback: if demo.gif > 5 MB, use demo-print.tape (the claude -p flow). + +Output docs/public/demo.gif +Output docs/public/demo.mp4 + +Set Shell bash +Set FontSize 18 +Set Width 1200 +Set Height 700 +Set Padding 20 +Set Theme Dracula +Set TypingSpeed 50ms +Set WaitTimeout 30s + +# ───────────────────────────────────────────────────────────────────────────── +# Frame 1 — cd into a pre-warmed demo folder (git-init'd so the agent doesn't +# stall on a repo-create prompt). Capture the HUD script's absolute path +# before cd'ing away (hidden from the recording — pure setup, not part of the +# story) so the render works regardless of repo checkout location. +# ───────────────────────────────────────────────────────────────────────────── +Hide +Type "HUD=$PWD/docs/public/demo-agent-hud.sh" +Enter +Type "DEMO_HOME=/tmp/agentplugins-demo-home" +Enter +Type "mkdir -p $DEMO_HOME" +Enter +Type "clear" +Enter +Show + +Type "cd /tmp/agentplugins-demo" +Enter +Sleep 500ms + +# ───────────────────────────────────────────────────────────────────────────── +# Frame 2 — type the prompt live (typed at the shell, read by the fake-HUD +# script below — purely for the visual of a natural-language ask). +# ───────────────────────────────────────────────────────────────────────────── +Type "# Read the agentplugins docs, scaffold a conventional-commits plugin, build it, push it, print Plugin is ready when done" +Enter +Sleep 500ms + +# ───────────────────────────────────────────────────────────────────────────── +# Frame 3 — run the scripted fake-agent HUD (gum banner + spinner + boxed +# tool-call lines), block on its marker (no Sleep-guessing). +# ───────────────────────────────────────────────────────────────────────────── +Type "bash $HUD" +Enter +Wait+Screen /Plugin is ready/ +Sleep 1s + +# ───────────────────────────────────────────────────────────────────────────── +# Frame 4 — clear before the install frame. +# ───────────────────────────────────────────────────────────────────────────── +Type "clear" +Enter +Sleep 500ms + +# ───────────────────────────────────────────────────────────────────────────── +# Frame 5 — install the plugin into the system. +# ───────────────────────────────────────────────────────────────────────────── +Type "HOME=$DEMO_HOME agentplugins add sigilco/agentplugins-conventional-commits -y" +Enter +Wait+Screen /Installed to:/ +Sleep 2s diff --git a/mise.toml b/mise.toml index 8b9c546..52d48d8 100644 --- a/mise.toml +++ b/mise.toml @@ -1,3 +1,4 @@ [tools] pnpm = "11" node = "24" +"aqua:charmbracelet/gum" = "0.17.0"