can1357/oh-my-pi · error · Error

`omp gallery --screenshot` requires VHS, which is not instal

Error message

`omp gallery --screenshot` requires VHS, which is not installed. Install it (e.g. `brew install vhs`, or see https://github.com/charmbracelet/vhs) and retry.

What it means

captureGalleryScreenshots renders gallery sections via VHS (charmbracelet/vhs), which must be on PATH. Before doing any work it probes for the binary with $which("vhs") and throws this instructional error when missing, so the failure is a clear setup message rather than a confusing spawn ENOENT later.

Source

Thrown at packages/coding-agent/src/cli/gallery-screenshot.ts:64

	/**
	 * Output destination. When omitted, PNGs land in a fresh temp directory.
	 * With multiple images the path is suffixed (`name-01.png`, `name-02.png`).
	 */
	out?: string;
}

/**
 * Capture the gallery sections as one or more PNGs and return their absolute
 * paths. Tall galleries are split across images so no single capture exceeds
 * the terminal-canvas height limit.
 */
export async function captureGalleryScreenshots(
	sections: GallerySection[],
	options: GalleryScreenshotOptions,
): Promise<string[]> {
	const vhs = $which("vhs");
	if (!vhs) {
		throw new Error(
			"`omp gallery --screenshot` requires VHS, which is not installed. " +
				"Install it (e.g. `brew install vhs`, or see https://github.com/charmbracelet/vhs) and retry.",
		);
	}

	const font = options.font ?? DEFAULT_SCREENSHOT_FONT;
	const fontSize = options.fontSize ?? DEFAULT_SCREENSHOT_FONT_SIZE;
	const cellHeight = fontSize * Math.max(LINE_HEIGHT, 1) * CELL_HEIGHT_RATIO;
	const cellWidth = fontSize * CELL_WIDTH_RATIO;
	const rowBudget = Math.max(40, Math.floor((MAX_IMAGE_HEIGHT_PX - 2 * PADDING) / cellHeight) - 2);
	const chunks = chunkGallerySections(sections, rowBudget);
	const themeJson = buildVhsTheme();

	const baseDir = options.out
		? path.dirname(path.resolve(options.out))
		: fs.mkdtempSync(path.join(os.tmpdir(), "omp-gallery-"));
	await fs.promises.mkdir(baseDir, { recursive: true });

View on GitHub (pinned to 9690622007)

Solutions

1. Install VHS: `brew install vhs` (see https://github.com/charmbracelet/vhs for other platforms)
2. Verify with `which vhs` that the binary is on PATH; fix PATH if installed elsewhere
3. In CI, add a step installing vhs before running the screenshot command

Example fix

// before (fails)
omp gallery --screenshot
// after
brew install vhs
omp gallery --screenshot

import { $which } from "@oh-my-pi/pi-utils";
if (!$which("vhs")) {
  throw new Error("vhs is required for gallery screenshots: brew install vhs");
}

When it happens

Trigger: Running `omp gallery --screenshot` on a machine where the `vhs` executable is not installed or not on PATH (minimal CI image, fresh dev machine, PATH lacking the install prefix).

Common situations: Fresh macOS/Linux setup without brew-installed vhs; CI containers missing the dependency; nix/venv style environments where PATH is restricted; vhs installed but under a name not on PATH.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• VHS failed to render the gallery screenshot${detail ? `: ${d
• Unsupported shell${shell ? ` "${shell}"` : ""}. Supported sh
• GitHub CLI returned invalid JSON output.
• --environment must be docker|apple-container
• harbor not found on PATH. Install with: uv tool install harb

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/7ab1e82c237a566d. Report an issue: GitHub.