@byokit/herdr weekly downloads statistics

<h1 align="center">@byokit/herdr</h1> <p align="center"> <img alt="status: in development" src="https://img.shields.io/badge/status-in%20development-lightgrey?style=flat" /> <a href="https://github.com/umeranjum17/byokit/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/umeranjum17/byokit/ci.yml?style=flat&branch=main" /></a> <a href="LICENSE"><img alt="Apache 2.0" src="https://img.shields.io/badge/license-Apache--2.0-666?style=flat" /></a> </p> <p align="center"><strong>Drive the Herdr already on this computer from an app, or from a phone.</strong><br/> Workspaces, tabs, panes, coding agents and blocked-approval answers, from a Node app or handed to a phone over <a href="../pair"><code>@byokit/pair</code></a>. Each agent inside Herdr keeps its own subscription login; the kit never sees a credential.</p> <p align="center">_{Phone-link apps depend on <a href="../pair"><code>@byokit/pair</code></a> and its examples import from there; the kit ships <code>@byokit/pair</code>, <code>@byokit/discover</code> and <code>@byokit/relay</code> as optional peers that only the <code>@byokit/herdr/link</code> entry loads, so a cli-only install stays small.}</p> <p align="center"> <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/3-agent.png" width="240" alt="Phone page titled Agents, Connected to Kitchen computer - same Wi-Fi.: two Pi agents marked Ready for you, and under Talk to it the agent's screen reading '> Add a --json flag to export', 'Read src/cli/export.ts', 'Edited src/cli/export.ts +18 -3' and 'export --json now prints JSON.' above a Message box, a Send button and Waiting for the reply below." /> <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/4-question.png" width="240" alt="Phone page with Questions for you at the top: Pi, Waiting for your answer., the question 'Allow this? (y/n)' and buttons Allow, Deny and Skip; below, the second Pi agent marked Waiting for your answer." /> <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/5-answered.png" width="240" alt="Phone page after the answer: no Questions for you section, both Pi agents marked Ready for you, and the agent's screen ending in 'Allow this? (y/n)', 'y' and 'npm test: 42 passing'" /> </p> <p align="center">_{The <a href="../../examples/herdr-kit">herdr-kit example</a>'s phone page: an agent at work, its question, answered. Captured by the example's e2e in a phone-sized headless Chromium, against the kit's stand-in Herdr.}</p> <p align="center"> <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/docs/images/herdr-kit-host.png" width="420" alt="Terminal running npm start -- --herdr &quot;$(command -v herdr)&quot; --via lan --name 'Kitchen computer': a QR code, then 'On the phone, scan this, or open http://192.168.1.144:7310/ and type K3J8-CJZ7-SE4R', 'Codes last five minutes. Press Enter for new ones.', 'Connecting to Herdr…' and 'Connected to Herdr.'" /> </p> <p align="center">_{The same example's host terminal (<code>host.ts</code>), started with <code>BYOKIT_EXAMPLE_FAKE=1</code> so it runs the kit's stand-in Herdr.}</p>

Install

npm install @byokit/herdr

The base install covers the kit itself (HerdrKit, cli, agents, ./binary): no React Native or native-crypto packages come along. Serving a link (@byokit/herdr/link) additionally needs the optional peers @byokit/pair, @byokit/discover and @byokit/relay in the app — npm install @byokit/pair @byokit/discover @byokit/relay — and importing the entry without one says exactly which.

· Latest release · All releases

Quickstart

Available on npm; it is also used from this repo, or from its packed packages as examples/herdr-kit does:

npm install @byokit/herdr

Herdr itself is not an npm dependency: the app installs Herdr 0.9.1 (see herdr.dev) and passes its path as bin. The opt-in helper ensureHerdr (@byokit/herdr/binary, also spelled fetchHerdr) fetches that for the app: it downloads the pinned release asset for the current platform into an app-owned directory, verifies its sha256 against a committed per-platform table, marks it executable, and returns the absolute bin for own mode. Nothing downloads on install or import — the network happens only when the helper is called. This runs against the kit's stand-in Herdr from @byokit/herdr/testing, so it needs neither Herdr nor an agent:

import { mkdtempSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { HerdrKit, agentWords, type BlockedAgent } from '@byokit/herdr';
import { startFakeHerdr } from '@byokit/herdr/testing';

// The kit's stand-in Herdr. With a real one, pass its bin and socket path instead.
const fake = await startFakeHerdr({ dir: mkdtempSync(join(tmpdir(), 'herdr-')) });
const kit = new HerdrKit({ mode: 'adopt', bin: fake.bin, socketPath: fake.socketPath });
await kit.start();

const agent = { paneId: 'w1:p2' };
await kit.prompt(agent, 'hello');                     // resolves with a receipt once delivered
console.log(await kit.wait(agent, { until: ['idle'], timeoutMs: 5000 }));
console.log((await kit.read(agent.paneId)).text);…