What is riff CLAUDE.md?

Project instructions for Riff, a codebase that lets a smart ring control keyboard actions and lets a computer read AI agent responses aloud. It covers the ring bridge, voice narrator, communication protocol, and build commands.

Use it when building or debugging the macOS ring-to-keyboard service, the voice narrator, speech queues, agent-specific voices, interruptions, speed controls, or their Unix-socket connection.

It gives an agent the project’s structure and operating details before it changes or runs the code.

riff CLAUDE.md — Instructions file for coding agents by remotehumans: Project instructions for Riff, a codebase that lets a…

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods

npx agentmods add instructions/remotehumans/riff/claude-md

Clone the repo

git clone --depth 1 https://github.com/remotehumans/riff

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/instructions/remotehumans/riff/claude-md.svg)](https://agentmods.dev/instructions/remotehumans/riff/claude-md)

Your own site

<a href="https://agentmods.dev/instructions/remotehumans/riff/claude-md"><img src="https://agentmods.dev/badge/instructions/remotehumans/riff/claude-md.svg" alt="Measured on agentmods" height="20"></a>

Per session 403 This file is loaded in full into every session.

When invoked 403 The same file — it is already loaded in full.

Security scan A 0 findings. Scan, not verified.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5	$0.00403	$0.00403
Opus 5	$0.00201	$0.00201
Sonnet 5	$0.00081	$0.00081
Haiku 4.5	$0.00040	$0.00040

Measured 4d ago against content hash df58dc49c3d9, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

riff CLAUDE.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 4d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

CLAUDE.md · 47 lines

What it actually says

Riff

Monorepo for hands-free AI interaction — smart ring input and voice narrator.

Components

riff-bridge

macOS daemon that bridges a JX-11 smart ring (BLE HID) to keyboard events for hands-free voice interaction.

Tap: Toggle Left Option key (voice-to-text push-to-talk)
Swipe right: Enter key (submit messages)
Swipe left: Backspace/Delete

Uses IOKit HID Manager for device-specific detection (VendorID/ProductID) and CGEvent tap to block default media key behavior.

riff-voice

Voice narrator daemon that speaks AI agent output aloud using MLX-Audio Kokoro TTS.

FIFO queue: Multiple sessions send text, one voice at a time
Per-agent voices: 54 Kokoro presets mapped by project directory
Session announcements: "project-name says:" before each message
Interrupt support: Stop speech instantly via riff-ctl interrupt or ring Escape button
Speed control: Adjustable playback speed (0.5-3.0x) via riff-ctl speed

Socket protocol over /tmp/riff.sock. Claude Code Stop hook auto-sends summaries.

Build & Run

riff-bridge

cd riff-bridge
swiftc riff_bridge.swift -o riff-bridge -framework CoreGraphics -framework IOKit
./riff-bridge

Requires macOS Accessibility permission. Signed with Apple Development certificate for stable permissions across recompiles.

LaunchAgent: ~/Library/LaunchAgents/co.remotehumans.riff-bridge.plist

riff-voice

cd riff-voice
make install    # uv sync + LaunchAgent + CLI symlinks + hook
riff-say "hello"
riff-ctl status

LaunchAgent: ~/Library/LaunchAgents/co.remotehumans.riff-voice.plist

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

4d ago First seen · 47 lines · 403 tokens per session scan A df58dc49c3d9

Subscribe to this mod's changes

riff CLAUDE.md is an instructions file published in the GitHub repository remotehumans/riff (24 stars, last pushed 21d ago), licensed MIT. It adds 403 tokens to every session, about $0.0020 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Hardware and IoT

riff CLAUDE.md

Getting it into your agent

Wrote this? Show the measurements

What it costs to keep this loaded

Grade A, and why

Nothing flagged

What it actually says

Riff

Components

riff-bridge

riff-voice

Build & Run

riff-bridge

riff-voice

What this file has done since we first saw it

Other instructions, from other repositories

firmware CLAUDE.md

Tutorial_AwesomeModernCPP AGENTS.md

brilliant_sdk AGENTS.md

NeoMind CLAUDE.md

zmk-config AGENTS.md

ext-apps CLAUDE.md