Himd

hi.md Plugin

hi.md is a voice-first /hi companion for Claude Code.

What it does

Type /hi, speak naturally, and himd will:

1. Capture your voice from the microphone
2. Analyze both your words and vocal signals (energy, pace, pauses)
3. Generate a warm, context-aware reply
4. Speak the reply aloud

Prerequisites

• macOS with Command Line Tools installed, or Windows with Visual Studio Build Tools
• Claude Code CLI
• Rust 1.88+ (for building from source)

Install from source

git clone https://github.com/tpiperatgod/hi.md.git
cd himd
cargo build --release

• macOS: binary at target/release/himd
• Windows: binary at target\release\himd.exe

Install from release artifact

If a binary has been published for your platform, download it from GitHub Releases. Release artifacts are published manually and may lag the current branch state:

macOS:

• Apple Silicon Mac → himd-darwin-arm64.tar.gz
• Intel Mac → himd-darwin-x64.tar.gz

tar xzf himd-darwin-*.tar.gz
chmod +x himd
# Remove macOS quarantine if needed:
xattr -d com.apple.quarantine himd

Windows:

• himd-windows-x64.zip

Expand-Archive .\himd-windows-x64.zip -DestinationPath .\himd

Register the MCP server

The MCP server name is voice-bridge (unchanged from the Node era).

Source install (project scope)

macOS/Linux:

claude mcp add --scope project --transport stdio -e DASHSCOPE_API_KEY=your-dashscope-key voice-bridge -- $(pwd)/target/release/himd serve-stdio

Windows:

claude mcp add --scope project --transport stdio -e DASHSCOPE_API_KEY=your-dashscope-key voice-bridge -- C:\path\to\himd\target\release\himd.exe serve-stdio

Release install (user scope)

macOS/Linux:

claude mcp add --scope user --transport stdio -e DASHSCOPE_API_KEY=your-dashscope-key voice-bridge -- /path/to/himd serve-stdio

Windows:

claude mcp add --scope user --transport stdio -e DASHSCOPE_API_KEY=your-dashscope-key voice-bridge -- C:\path\to\himd.exe serve-stdio

Or use the guided setup inside Claude Code:

/himd:setup

Migrating from legacy Node registration

If you previously registered the Node.js @himd/voice-bridge package, remove it and re-register with the Rust binary:

# Remove the old registration
claude mcp remove voice-bridge

# Re-register with the Rust binary (see commands above)
/himd:setup

The MCP server name remains voice-bridge so existing Claude sessions continue to work.

Configure API key

macOS/Linux:

export DASHSCOPE_API_KEY="your-key"
# Add to ~/.zshrc to persist

Windows (PowerShell):

$env:DASHSCOPE_API_KEY = "your-key"
# Add to $PROFILE to persist

Get your key at DashScope.

Verify setup

himd doctor           # human-readable output
himd doctor --json    # machine-readable output (used by /himd:doctor)

Or inside Claude Code:

/himd:doctor

Use /hi

1. Open Claude Code
2. Type /hi
3. Speak when prompted
4. Listen to the reply

Persona customization

/hi supports one optional project-local persona file:

• active file: .himd/persona.md
• if the file exists, /hi uses it for reply style and TTS defaults
• if the file does not exist, /hi falls back to the built-in default caring companion

Use a preset

Choose a preset from plugins/himd/personas/zh/presets/ (Chinese-authored) or plugins/himd/personas/en/presets/ (English-authored), then copy it into .himd/persona.md. The filenames are mirrored across both directories.

macOS/Linux:

mkdir -p .himd
cp plugins/himd/personas/zh/presets/gentle.md .himd/persona.md
# or
cp plugins/himd/personas/en/presets/gentle.md .himd/persona.md

Windows (PowerShell):

New-Item -ItemType Directory -Force .himd | Out-Null
Copy-Item plugins/himd/personas/zh/presets/gentle.md .himd/persona.md
# or
Copy-Item plugins/himd/personas/en/presets/gentle.md .himd/persona.md

Available presets in both zh/ and en/:

• gentle.md — gentle, restrained, low-stimulation
• plain.md — plain, natural, no cutesiness
• sharp.md — direct, clear-headed, lightly sharp
• tsundere.md — prickly on the surface, caring underneath
• english-buddy.md — bilingual companion for natural everyday English
• english-coach.md — bilingual coach that pushes spoken English practice

Create your own

Start from either template:

macOS/Linux:

mkdir -p .himd
cp plugins/himd/personas/zh/TEMPLATE.md .himd/persona.md
# or
cp plugins/himd/personas/en/TEMPLATE.md .himd/persona.md

Windows (PowerShell):

New-Item -ItemType Directory -Force .himd | Out-Null
Copy-Item plugins/himd/personas/zh/TEMPLATE.md .himd/persona.md
# or
Copy-Item plugins/himd/personas/en/TEMPLATE.md .himd/persona.md

Then edit .himd/persona.md directly.

There is no separate persona command and no layered override chain. The current persona is always exactly the contents of .himd/persona.md.

For the full directory layout, see plugins/himd/personas/README.md.

Plugin commands

Command	Description
/hi	Start a voice conversation
/himd:setup	Guided setup for the MCP server (source or release install)
/himd:doctor	Diagnose setup and runtime issues

Troubleshooting

• "voice-bridge tools unavailable" — run /himd:setup to register the MCP server
• Missing DASHSCOPE_API_KEY — set it in your shell profile and restart Claude Code
• Binary not found — source: run cargo build --release; release: re-download the artifact
• Quarantine error on macOS — run xattr -d com.apple.quarantine /path/to/himd
• Legacy Node registration — if /himd:doctor shows a registration pointing to npx @himd/voice-bridge, remove it and re-register with the Rust binary
• Setup seems broken — run /himd:doctor for guided diagnosis

Local verification

This repository does not maintain GitHub Actions workflows. Verify changes locally before publishing plugin docs or preparing a manual release:

cargo test --workspace -- --test-threads=1
cargo clippy --workspace -- -D warnings
cargo fmt --all --check