repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

add asciinema demo workflow

6a97080540ddfd21a219a09dd68ff4eaf6397311

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (17)

pi/.gitignore

Modified
8 8 **/node_modules/
9 9 research/
10 10 .tmp/
11 +.demo/

pi/agent/extensions/context-size/README.md

Added
new file mode 100644
1 +# context-size
3 +Pi context-window usage telemetry.
5 +Emits a `footer:segment` when `@bugabinga/pi-ext-footer` is loaded; otherwise falls back to Pi status text.
7 +## Demo
9 +<!-- demo:footer_suite:start -->
10 +![Footer suite](assets/footer_suite.gif)
11 +<!-- demo:footer_suite:end -->

pi/agent/extensions/context-size/assets/footer_suite.gif

Added
new file mode 100644

Current version contains binary or non-UTF-8 data.

pi/agent/extensions/cost/README.md

Added
new file mode 100644
1 +# cost
3 +Pi model, token, and cost telemetry.
5 +Shows model id, last-turn tokens, session cost, and monthly cost. Uses `footer:segment` with `@bugabinga/pi-ext-footer`; otherwise falls back to Pi status text.
7 +## Demo
9 +<!-- demo:footer_suite:start -->
10 +![Footer suite](assets/footer_suite.gif)
11 +<!-- demo:footer_suite:end -->

pi/agent/extensions/cost/assets/footer_suite.gif

Added
new file mode 100644

Current version contains binary or non-UTF-8 data.

pi/agent/extensions/footer/README.md

Added
new file mode 100644
1 +# footer
3 +Shared Pi footer renderer.
5 +Renders `footer:segment` events from producer extensions into stable workspace/LLM rows and includes Pi extension statuses as the last row.
7 +## Demo
9 +<!-- demo:footer_suite:start -->
10 +![Footer suite](assets/footer_suite.gif)
11 +<!-- demo:footer_suite:end -->

pi/agent/extensions/footer/assets/footer_suite.gif

Added
new file mode 100644

Current version contains binary or non-UTF-8 data.

pi/agent/extensions/git-status/README.md

Added
new file mode 100644
1 +# git-status
3 +Pi workspace git telemetry.
5 +Shows cwd, branch, ahead/behind, stash, and dirty-state indicators. Uses `footer:segment` with `@bugabinga/pi-ext-footer`; otherwise falls back to Pi status text.
7 +## Demo
9 +<!-- demo:footer_suite:start -->
10 +![Footer suite](assets/footer_suite.gif)
11 +<!-- demo:footer_suite:end -->

pi/agent/extensions/git-status/assets/footer_suite.gif

Added
new file mode 100644

Current version contains binary or non-UTF-8 data.

pi/agent/extensions/quota/README.md

Added
new file mode 100644
1 +# quota
3 +Subscription quota dashboard for Pi providers.
5 +Supports Anthropic, OpenAI Codex, MiniMax, Zai, and Kimi. `/quota` toggles the detailed widget. Uses `footer:segment` with `@bugabinga/pi-ext-footer`; otherwise falls back to Pi status text.
7 +## Demo
9 +<!-- demo:footer_suite:start -->
10 +![Footer suite](assets/footer_suite.gif)
11 +<!-- demo:footer_suite:end -->

pi/agent/extensions/quota/assets/footer_suite.gif

Added
new file mode 100644

Current version contains binary or non-UTF-8 data.

pi/agent/extensions/runtime/README.md

Added
new file mode 100644
1 +# runtime
3 +Pi project runtime telemetry.
5 +Detects common runtime files in cwd/parents and shows runtime version. Uses `footer:segment` with `@bugabinga/pi-ext-footer`; otherwise falls back to Pi status text.
7 +## Demo
9 +<!-- demo:footer_suite:start -->
10 +![Footer suite](assets/footer_suite.gif)
11 +<!-- demo:footer_suite:end -->

pi/agent/extensions/runtime/assets/footer_suite.gif

Added
new file mode 100644

Current version contains binary or non-UTF-8 data.

pi/agent/prompts/drive-demo.md

Added
new file mode 100644
1 +---
2 +description: Create or refine an interactive Pi demo driver and GIF recording workflow
3 +argument-hint: "<extension-or-demo-name>"
4 +---
5 +Create/refine demo driver for `$ARGUMENTS`.
7 +Goal: animated GIF only. No screenshot. Use asciinema + pexpect + agg.
9 +Rules:
10 +- Manual workflow only; never run from check/release gates.
11 +- Driver files live in `drivers/*.py`; readable, small, commentable.
12 +- `scripts/demo.py` is engine; drivers contain data/steps only.
13 +- `just demo <name>` delegates to `python3 scripts/demo.py <name>`.
14 +- README missing → fail. Do not create README silently.
15 +- Assets land in each target extension: `agent/extensions/<target>/assets/<demo>.gif`.
16 +- README updated only between markers:
17 + `<!-- demo:<name>:start -->` … `<!-- demo:<name>:end -->`.
18 +- No screenshots. GIF is source of truth for visual QA.
20 +Recording defaults:
21 +- cols: 100
22 +- rows: 28
23 +- theme: Pi default; do not force `--theme dark`.
24 +- cwd: choose demo-friendly extension/project dir.
25 +- Pi isolation flags:
26 + `--no-session --no-context-files --no-skills --no-prompt-templates --no-extensions`
27 +- Load exact extensions with `-e ./agent/extensions/<name>`.
28 +- For footer concert demos, load footer + client extensions together; do not make ephemeral fixture extensions.
29 +- Real LLM/quota calls OK for manual demos.
31 +Pexpect driving:
32 +- Spawn real interactive `pi` in PTY with fixed dimensions.
33 +- Actively pump child output to stdout; sleeping alone records empty casts.
34 +- Type commands/prompts char-by-char with deliberate delay so GIF shows typing.
35 +- Pause before Enter.
36 +- Use longer holds for human readability.
37 +- Modifiers/key overlays: skip unless Pi visibly reacts; asciinema has no native modifier overlay here.
39 +Good pacing baseline:
40 +- startup settle: 5s
41 +- command typing delay: ~55–75ms/char
42 +- prompt typing delay: ~35–55ms/char
43 +- post `/quota`: 6–7s
44 +- post `/footer` hide: 4s
45 +- post `/footer` show: 5–6s
46 +- LLM prompt wait: 14–18s or until clear final output if reliable
47 +- final hold: 5–6s
49 +Asciinema:
50 +- record with `--headless --overwrite --capture-input --window-size 100x28 -i 4.0`
51 +- output `.demo/<name>.cast`
53 +Agg:
54 +- render GIF from cast:
55 + `agg --cols 100 --rows 28 --theme asciinema --text-font-family "JetBrains Mono" --font-size 14 --line-height 1.25 --idle-time-limit 4.0 --last-frame-duration 5 --fps-cap 24 <cast> <gif>`
57 +QA:
58 +- Inspect GIF, not `.txt`, as visual truth.
59 +- Also generate text for quick sanity:
60 + `asciinema convert -f txt <cast> <txt> --overwrite`
61 +- `.txt` may show duplicate lines/artifacts from terminal control sequences; acceptable if GIF looks good.
62 +- Avoid `asciinema play` in main terminal; it can disturb visible scrollback due recorded control sequences.
64 +Driver shape:
65 +```py
66 +title = "Footer suite"
67 +extensions = ["footer", "context-size", "cost", "git-status", "runtime", "quota"]
68 +targets = ["footer", "context-size", "cost", "git-status", "runtime", "quota"]
69 +cols = 100
70 +rows = 28
71 +cwd = "agent/extensions/lucifiber"
72 +steps = [
73 + ("wait", 5000),
74 + ("command", "/quota", 7000),
75 + ("prompt", "In one short sentence, say what this directory contains.", 16000),
76 + ("command", "/footer", 4000),
77 + ("command", "/footer", 6000),
78 + ("prompt", "Now answer with exactly three words: footer status dashboard.", 14000),
79 + ("wait", 6000),
81 +```
83 +Supported step ops should stay tiny:
84 +- `wait(ms)`
85 +- `type(text[, delay_ms])`
86 +- `send(text)`
87 +- `command(text[, after_ms])` — type text slowly, pause, Enter, wait
88 +- `prompt(text[, after_ms])` — type prompt slowly, pause, Enter, wait
89 +- `ctrl(key)`
90 +- `quit()`
92 +When asked to create a driver:
93 +1. Pick visual story: what user sees, why ext matters.
94 +2. Pick exact extensions and targets.
95 +3. Add/read driver in `drivers/`.
96 +4. Run smoke once to `/tmp/<demo>.gif` first.
97 +5. Ask user to inspect GIF before committing assets/README changes.

pi/drivers/footer_suite.py

Added
new file mode 100644
1 +title = "Footer suite"
3 +extensions = [
4 + "footer",
5 + "context-size",
6 + "cost",
7 + "git-status",
8 + "runtime",
9 + "quota",
12 +targets = [
13 + "footer",
14 + "context-size",
15 + "cost",
16 + "git-status",
17 + "runtime",
18 + "quota",
21 +cols = 100
22 +rows = 28
23 +cwd = "agent/extensions/lucifiber"
25 +steps = [
26 + ("wait", 5000),
27 + ("command", "/quota", 6000),
28 + ("prompt", "In one short sentence, say what this directory contains.", 16000),
29 + ("command", "/footer", 4000),
30 + ("command", "/footer", 6000),
31 + ("prompt", "Now answer with exactly three words: footer status dashboard.", 14000),
32 + ("wait", 6000),

pi/justfile

Modified
4 4 _default:
5 5 python3 scripts/extensions.py list
7 7 check ext="":
8 8 python3 scripts/extensions.py check {{ ext }}
10 +demo name:
11 + python3 scripts/demo.py {{ name }}
10 13 fmt:
11 14 just --fmt

pi/scripts/demo.py

Added
new file mode 100755
1 +#!/usr/bin/env python3
2 +"""Record interactive Pi extension demos."""
4 +from __future__ import annotations
6 +import argparse
7 +import importlib.util
8 +import shutil
9 +import subprocess
10 +import sys
11 +import time
12 +from dataclasses import dataclass
13 +from pathlib import Path
14 +from types import ModuleType
16 +try:
17 + import pexpect
18 +except ImportError as e:
19 + raise SystemExit("missing Python package: pexpect") from e
21 +ROOT = Path(__file__).resolve().parents[1]
22 +DRIVERS = ROOT / "drivers"
23 +EXTENSIONS = ROOT / "agent" / "extensions"
24 +OUT = ROOT / ".demo"
26 +CAST_IDLE_LIMIT = "4.0"
27 +AGG_ARGS = [
28 + "--theme", "asciinema",
29 + "--text-font-family", "JetBrains Mono",
30 + "--font-size", "14",
31 + "--line-height", "1.25",
32 + "--idle-time-limit", "4.0",
33 + "--last-frame-duration", "5",
34 + "--fps-cap", "24",
38 +@dataclass(frozen=True)
39 +class Driver:
40 + name: str
41 + title: str
42 + extensions: list[str]
43 + targets: list[str]
44 + cols: int
45 + rows: int
46 + cwd: Path
47 + steps: list[tuple]
50 +def load_module(name: str) -> ModuleType:
51 + path = DRIVERS / f"{name}.py"
52 + if not path.exists():
53 + raise SystemExit(f"driver not found: {path}")
54 + spec = importlib.util.spec_from_file_location(f"driver_{name}", path)
55 + if spec is None or spec.loader is None:
56 + raise SystemExit(f"cannot load driver: {path}")
57 + module = importlib.util.module_from_spec(spec)
58 + spec.loader.exec_module(module)
59 + return module
62 +def str_list(module: ModuleType, attr: str) -> list[str]:
63 + value = getattr(module, attr, None)
64 + if not isinstance(value, list) or not all(isinstance(x, str) and x for x in value):
65 + raise SystemExit(f"driver {module.__name__}: {attr} must be non-empty string list")
66 + return value
69 +def load_driver(name: str) -> Driver:
70 + module = load_module(name)
71 + title = getattr(module, "title", name.replace("_", " ").title())
72 + if not isinstance(title, str) or not title:
73 + raise SystemExit("title must be string")
75 + cols = getattr(module, "cols", 100)
76 + rows = getattr(module, "rows", 28)
77 + if not isinstance(cols, int) or not isinstance(rows, int) or cols < 40 or rows < 12:
78 + raise SystemExit("cols/rows must be reasonable ints")
80 + cwd_raw = getattr(module, "cwd", ".")
81 + if not isinstance(cwd_raw, str):
82 + raise SystemExit("cwd must be string")
83 + cwd = (ROOT / cwd_raw).resolve()
84 + if not cwd.is_dir():
85 + raise SystemExit(f"cwd missing: {cwd}")
87 + steps = getattr(module, "steps", None)
88 + if not isinstance(steps, list):
89 + raise SystemExit("steps must be list")
90 + for step in steps:
91 + validate_step(step)
93 + driver = Driver(
94 + name=name,
95 + title=title,
96 + extensions=str_list(module, "extensions"),
97 + targets=str_list(module, "targets"),
98 + cols=cols,
99 + rows=rows,
100 + cwd=cwd,
101 + steps=steps,
103 + validate_driver(driver)
104 + return driver
107 +def validate_step(step: object) -> None:
108 + if not isinstance(step, tuple) or not step:
109 + raise SystemExit(f"invalid step: {step!r}")
110 + op = step[0]
111 + if op not in {"wait", "type", "send", "command", "prompt", "ctrl", "quit"}:
112 + raise SystemExit(f"unknown step op: {op!r}")
113 + if op == "wait" and not (len(step) == 2 and isinstance(step[1], int)):
114 + raise SystemExit(f"wait step must be ('wait', ms): {step!r}")
115 + if op in {"type", "send"} and not (len(step) in {2, 3} and isinstance(step[1], str)):
116 + raise SystemExit(f"{op} step must include text: {step!r}")
117 + if op in {"command", "prompt"} and not (len(step) in {2, 3} and isinstance(step[1], str)):
118 + raise SystemExit(f"{op} step must include text: {step!r}")
119 + if op == "ctrl" and not (len(step) == 2 and isinstance(step[1], str) and len(step[1]) == 1):
120 + raise SystemExit(f"ctrl step must be ('ctrl', key): {step!r}")
121 + if op == "quit" and len(step) != 1:
122 + raise SystemExit(f"quit step takes no args: {step!r}")
125 +def validate_driver(driver: Driver) -> None:
126 + for name in driver.extensions:
127 + if not (EXTENSIONS / name / "index.ts").exists():
128 + raise SystemExit(f"extension missing index.ts: {name}")
129 + for name in driver.targets:
130 + ext = EXTENSIONS / name
131 + if not ext.is_dir():
132 + raise SystemExit(f"target extension missing: {name}")
133 + if not (ext / "README.md").exists():
134 + raise SystemExit(f"target README missing: {ext / 'README.md'}")
137 +def pi_command(driver: Driver) -> str:
138 + parts = [
139 + "pi",
140 + "--no-session",
141 + "--no-context-files",
142 + "--no-skills",
143 + "--no-prompt-templates",
144 + "--no-extensions",
146 + for name in driver.extensions:
147 + parts.extend(["-e", str(EXTENSIONS / name)])
148 + return " ".join(shlex_quote(part) for part in parts)
151 +def shlex_quote(value: str) -> str:
152 + import shlex
153 + return shlex.quote(value)
156 +def pump(child: pexpect.spawn, seconds: float) -> None:
157 + end = time.time() + seconds
158 + while time.time() < end and child.isalive():
159 + try:
160 + data = child.read_nonblocking(size=8192, timeout=0.03)
161 + if data:
162 + sys.stdout.write(data)
163 + sys.stdout.flush()
164 + except pexpect.TIMEOUT:
165 + pass
166 + except pexpect.EOF:
167 + break
170 +def type_text(child: pexpect.spawn, text: str, delay: float) -> None:
171 + for ch in text:
172 + child.send(ch)
173 + pump(child, delay)
176 +def run_step(child: pexpect.spawn, step: tuple) -> bool:
177 + op = step[0]
178 + if op == "wait":
179 + pump(child, step[1] / 1000)
180 + elif op == "type":
181 + delay = (step[2] if len(step) > 2 else 55) / 1000
182 + type_text(child, step[1], delay)
183 + elif op == "send":
184 + child.send(step[1])
185 + pump(child, (step[2] if len(step) > 2 else 500) / 1000)
186 + elif op == "command":
187 + type_text(child, step[1], 0.055)
188 + pump(child, 0.35)
189 + child.send("\r")
190 + pump(child, (step[2] if len(step) > 2 else 1000) / 1000)
191 + elif op == "prompt":
192 + type_text(child, step[1], 0.035)
193 + pump(child, 0.45)
194 + child.send("\r")
195 + pump(child, (step[2] if len(step) > 2 else 12000) / 1000)
196 + elif op == "ctrl":
197 + child.sendcontrol(step[1])
198 + pump(child, 0.5)
199 + elif op == "quit":
200 + return True
201 + return False
204 +def drive(driver: Driver) -> int:
205 + child = pexpect.spawn(
206 + pi_command(driver),
207 + cwd=str(driver.cwd),
208 + encoding="utf-8",
209 + timeout=90,
210 + dimensions=(driver.rows, driver.cols),
212 + try:
213 + for step in driver.steps:
214 + if run_step(child, step):
215 + break
216 + finally:
217 + try:
218 + child.sendcontrol("c")
219 + pump(child, 1.0)
220 + except Exception:
221 + pass
222 + child.terminate(force=True)
223 + return 0
226 +def ensure_tools() -> None:
227 + missing = [tool for tool in ["asciinema", "agg"] if not shutil.which(tool)]
228 + if missing:
229 + raise SystemExit(f"missing tool(s): {', '.join(missing)}")
232 +def record(driver: Driver) -> tuple[Path, Path, Path]:
233 + ensure_tools()
234 + OUT.mkdir(exist_ok=True)
235 + cast = OUT / f"{driver.name}.cast"
236 + gif = OUT / f"{driver.name}.gif"
237 + txt = OUT / f"{driver.name}.txt"
239 + cmd = [
240 + "asciinema", "rec",
241 + "--headless",
242 + "--overwrite",
243 + "--capture-input",
244 + "--window-size", f"{driver.cols}x{driver.rows}",
245 + "-i", CAST_IDLE_LIMIT,
246 + "-c", f"python3 {shlex_quote(str(Path(__file__).resolve()))} --drive {shlex_quote(driver.name)}",
247 + str(cast),
249 + subprocess.run(cmd, cwd=ROOT, check=True)
251 + subprocess.run([
252 + "agg",
253 + "--cols", str(driver.cols),
254 + "--rows", str(driver.rows),
255 + *AGG_ARGS,
256 + str(cast),
257 + str(gif),
258 + ], cwd=ROOT, check=True)
260 + subprocess.run([
261 + "asciinema", "convert", "-f", "txt", str(cast), str(txt), "--overwrite",
262 + ], cwd=ROOT, check=True, stdout=subprocess.DEVNULL)
264 + return cast, gif, txt
267 +def readme_block(driver: Driver) -> str:
268 + return (
269 + f"<!-- demo:{driver.name}:start -->\n"
270 + f"![{driver.title}](assets/{driver.name}.gif)\n"
271 + f"<!-- demo:{driver.name}:end -->"
275 +def update_readme(readme: Path, driver: Driver) -> None:
276 + text = readme.read_text()
277 + start = f"<!-- demo:{driver.name}:start -->"
278 + end = f"<!-- demo:{driver.name}:end -->"
279 + block = readme_block(driver)
281 + if start in text and end in text:
282 + before, rest = text.split(start, 1)
283 + _, after = rest.split(end, 1)
284 + readme.write_text(before + block + after)
285 + return
287 + addition = f"\n\n## Demo\n\n{block}\n"
288 + readme.write_text(text.rstrip() + addition)
291 +def install_assets(driver: Driver, gif: Path) -> None:
292 + for name in driver.targets:
293 + ext = EXTENSIONS / name
294 + assets = ext / "assets"
295 + assets.mkdir(exist_ok=True)
296 + shutil.copy2(gif, assets / f"{driver.name}.gif")
297 + update_readme(ext / "README.md", driver)
298 + print(f"OK asset {name}/assets/{driver.name}.gif")
301 +def main() -> int:
302 + parser = argparse.ArgumentParser()
303 + parser.add_argument("name", nargs="?")
304 + parser.add_argument("--drive", dest="drive_name")
305 + parser.add_argument("--no-install", action="store_true")
306 + args = parser.parse_args()
308 + if args.drive_name:
309 + return drive(load_driver(args.drive_name))
310 + if not args.name:
311 + raise SystemExit("usage: scripts/demo.py <driver>")
313 + driver = load_driver(args.name)
314 + cast, gif, txt = record(driver)
315 + print(f"OK cast {cast}")
316 + print(f"OK gif {gif}")
317 + print(f"OK txt {txt}")
318 + if not args.no_install:
319 + install_assets(driver, gif)
320 + return 0
323 +if __name__ == "__main__":
324 + raise SystemExit(main())