npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

agentdock-pi-plugin

v0.3.0

Published

AgentDock BLE hardware controller bridge for the pi coding agent

Readme

AgentDock pi extension

A pi coding agent extension that bridges AgentDock hardware to pi over BLE.

It connects to an AgentDock-XXXX device, forwards key and encoder events to the pi API, and pushes the agent state back to the device so the LED shows what the agent is doing.

Requirements

  • Node.js 22 or newer
  • Bluetooth LE support on the host
  • The AgentDock firmware from ../firmware

On macOS, grant Bluetooth permission to the terminal application the first time the extension scans.

Install

Install it as a pi package:

pi install npm:agentdock-pi-plugin

To pin a version: pi install npm:[email protected]. Project scope: add -l. Remove with pi remove npm:agentdock-pi-plugin.

@stoprocent/noble is a native BLE binding installed as a dependency. On Linux you may need the Bluetooth headers first (for example libbluetooth-dev on Debian/Ubuntu).

Load without installing

During development:

pi --extension /absolute/path/to/agentdock/pi-plugin/index.ts

Or try the npm tarball for a single invocation:

pi -e npm:agentdock-pi-plugin

Usage

Run /dock inside pi to open the management panel:

  • select or rebind a device
  • edit the KEY2 / KEY3 macros
  • test LED states (including auto, which plays the full seven-colour cycle once)
  • set LED brightness and buzzer volume (applied live, persisted on the device)
  • force a reconnect

Configuration is stored in ~/.pi/agent/agentdock.json:

{
  "preferredDevice": "AgentDock-A1B2",
  "macros": ["继续", "不对"],
  "brightness": 100,
  "volume": 100
}

brightness / volume are a display cache only: the device's own NVS is the source of truth, and the values reported by the device on connect overwrite the local ones.

Controls

| Device input | pi action | |---|---| | KEY1 short press | Abort the current run | | KEY1 long press | Toggle the device buzzer mute (device-local) | | KEY2 short press | Send macro 0 (default 继续) | | KEY2 long press | Demo mode: bugle fanfare + seven-colour breathing LED (3 s, device-local) | | KEY3 short press | Send macro 1 (default 不对) | | KEY3 long press | Toggle the encoder click sound (device-local) | | Encoder push | Send 继续 | | Encoder rotate | Scroll the transcript by ±3 lines per step |

LED states

| State | Meaning | |---|---| | Dim blue | Idle | | Green breathing | Agent is running | | White double flash | Run finished | | Red triple flash | A tool returned an error | | Seven-colour breathing | Demo / auto LED test (3 s) | | Very dim blue heartbeat | Not connected |

Transcript scrolling

Scrolling relies on pi's fullscreen TUI internals. If the API is unavailable in your pi version, encoder events are logged and other features keep working.

Protocol

The extension talks to firmware/main/deck.c over a custom GATT service:

  • Service: 8e7c1a10-c0de-4b1e-9f6a-000000000001
  • EVENT notify (device → host): 8e7c1a10-c0de-4b1e-9f6a-000000000002
  • STATE write (host → device): 8e7c1a10-c0de-4b1e-9f6a-000000000003
// device -> host
{"k":"key","id":2}
{"k":"enc","v":-1}
{"k":"cfg","b":100,"v":80,"m":0,"c":1}   // 设备设置快照 (连接后立即推一次)

// host -> device
{"t":"s","st":"busy"}     // idle | busy | done | error | demo
{"t":"cfg","b":80,"v":60} // 亮度 / 音量 0~100 (设备落 NVS)

Development

npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest: 纯逻辑 + /dock 面板渲染与交互
npm run check:pack  # 校验 npm tarball 内容 (入口齐全、无测试泄漏)

Publishing is described in PUBLISHING.md, or in short:

npm version patch
npm publish --registry https://registry.npmjs.com/

单测不依赖真实蓝牙硬件: BLE 通道与 pi 的 ctx.ui 都是 mock 的, 主题用真实 ANSI 转义以保证宽度计算与线上一致。

Troubleshooting

  • Extension logs are prefixed with [agentdock] in non-TUI modes.
  • macOS: check System Settings → Privacy & Security → Bluetooth for the terminal application.
  • The extension scans for 8 seconds and retries every 5 seconds. The device shows a dim blue heartbeat while it is not connected.
  • Use npm run scan to list all visible BLE devices and verify that the device is advertising.