sugarcraft/candy-hermit

PHP port of Genekkion/theHermit — fuzzy finder / quick-fix overlay for terminal UIs. Wraps a background view, renders a filterable list overlay on top, background continues to update underneath.

v0.2.0 2026-05-07 01:29 UTC

Requires

• php: ^8.1

Requires (Dev)

• phpunit/phpunit: ^10.5

MIT

• Joe Huss

• finder
• overlay
• fuzzy
• tui
• sugarcraft
• quickfix

README

CandyHermit

PHP port of Genekkion/theHermit — fuzzy finder / quick-fix overlay for terminal UIs. Renders a filterable list overlay on top of a background view while the background continues to update.

Features

• Fuzzy filtering — filter list items as you type
• Overlay compositing — background view renders underneath; overlay chars replace background at specified positions
• Background continues updating — The Hermit doesn't block the underlying view
• Fully styleable — custom filter prompt, item format, matching highlight
• Pure renderer — no terminal I/O; output is strings you manage

Install

composer require sugarcraft/candy-hermit

Quick Start

use SugarCraft\Hermit\Hermit;

// Items to filter
$items = ['apple', 'banana', 'cherry', 'date', 'elderberry'];

// Create hermit with items
$h = Hermit::new($items)
    ->setPrompt('> ')
    ->setItemFormatter(fn($item, $selected) => ($selected ? '*' : ' ') . " $item");

// Show and type to filter
$h = $h->show();
$h = $h->type('ba');  // filter by 'ba'

echo $h->View("background content\nmore background");

// Navigate
$h = $h->cursorDown();
$h = $h->cursorUp();

// Select
$selected = $h->selected();  // currently selected item

// Hide
$h = $h->hide();

Model Interface

Implement the Model interface to use Hermit inside a larger Bubble-Tea-style application:

use SugarCraft\Hermit\Model;

class MyModel implements Model {
    public function update(Hermit $hermit, string $msg): Model { ... }
    public function view(Hermit $hermit): string { ... }
}

License

MIT