@ratitisrad/agentvoice

GitHub Actions

Renamed: this package is now `squeakr` — run `agentvoice migrate-to-squeakr`. Self-hosted voice bridge for Cursor, Codex, and Claude Code CLIs

Devops Developer Tools

Add to Cursor Add to VS Code Run on PlugMCP

GitHub npm Website

Add to Cursor Add to VS Code Run on PlugMCP

1{2  "mcpServers": {3    "ratitisrad-agentvoice": {4      "command": "npx",5      "args": [6        "-y",7        "@ratitisrad/[email protected]"8      ]9    }10  }11}

.cursor/mcp.jsonMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y @ratitisrad/[email protected]

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add ratitisrad-agentvoice -- npx -y @ratitisrad/agentvoice@0.1.6

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "ratitisrad-agentvoice": {4      "command": "npx",5      "args": [6        "-y",7        "@ratitisrad/[email protected]"8      ]9    }10  }11}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.1.6
Last checked: 2026-10-28

Stars: —
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install @ratitisrad/agentvoice?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does @ratitisrad/agentvoice need an API key?

No required environment variable is listed on this record.

What transport does @ratitisrad/agentvoice use?

@ratitisrad/agentvoice runs locally over stdio.

When was @ratitisrad/agentvoice last checked?

Last checked 2026-10-28. Renamed: this package is now `squeakr` — run `agentvoice migrate-to-squeakr`. Self-hosted voice bridge for Cursor, Codex, and Claude Code CLIs

From the publisher

Documentation

Speak from an iPhone native app (CallKit) or PWA; the active agent CLI is the reasoning layer via the squeakr MCP server (speak, done, next_voice_turn). Coding work is delegated to worker agents via spawn_agent. Speech is pluggable in both directions — listen with the browser, a self-hosted Whisper container (no key, audio never leaves the host), Groq, OpenAI, Deepgram, Gemini, ElevenLabs, OpenRouter or Amazon Transcribe; speak with the browser, a local Kokoro voice, ElevenLabs, OpenAI, Gemini, Deepgram, Groq or Polly. Each side is an ordered fallback chain that skips any provider which cannot handle the language, so a device with no Polish voice hands that reply to one that has one. Configured and keyed from Config → Speech — see docs/29, docs/30 and docs/31. If the CLI needs you to sign in, the app prompts you in place — see docs/24-agent-providers.md.

Networking defaults to Tailscale but is pluggable — Cloudflare Tunnel, ngrok, Azure Dev Tunnels, plain LAN, or your own reverse proxy also work, one-click from Config → Serve → Network. See docs/25-hosting-providers.md.

How it works

iPhone PWA (Vosk wake + STT + TTS)
        │  /ws/intelligence (app token)
        ▼
Bridge (Node/TS) ── VoiceTurnQueue ── MCP /mcp ──► voice agent (agent CLI)
        │                                              │
        │                                              ▼ spawn_agent
        └──────────────────────────────────────► agent CLI workers → git

Default workflow: agent_native — see docs/16-mcp-server-agent-as-brain.md.

Alternate: llm_intelligence — Claude on Bedrock orchestrates tools.

Install

Squeakr ships as an npm package. The bridge and the built web app come in the same tarball — no checkout, no build step. Install it globally:

npm install -g squeakr
squeakr setup      # guided: agent CLI + projects, then hosting such as Tailscale

-g makes it a system tool rather than a project dependency: npm installs the package into <prefix>/lib/node_modules/squeakr and links the squeakr command into <prefix>/bin, on your PATH.

It runs as a background service out of the box. A global install registers and starts a user service — systemd on Linux, launchd on macOS — so the bridge is up at http://127.0.0.1:5089 straight away and comes back at every login; npm update -g squeakr restarts it on the new version. It listens on this machine only: nothing is exposed until you set up hosting. Skip it with SQUEAKR_NO_SERVICE=1 npm install -g …; on Windows, or if your npm is set to ignore install scripts, run squeakr service install --now once. Before uninstalling, stop it with squeakr service uninstall (npm runs no uninstall hooks).

squeakr setup is the same wizard on every install — npm, a .deb/.rpm, or a clone (where scripts/setup.sh builds first and then runs it). It asks whether you want the background service (already there after npm install -g), sets up the agent CLI and where your repos live, and — with the service — sets up hosting: Tailscale, Cloudflare Tunnel, ngrok, Dev Tunnels or LAN, so your phone can reach it. --yes takes every default; --no-service, --service --hosting tailscale, --agent, --projects-dir answer individual questions for scripts.

The bridge keeps everything in a home directory — ~/.squeakr, or $SQUEAKR_HOME — seeded on first start: config.json from the packaged example and a random APP_TOKEN in ~/.squeakr/.env. Open http://127.0.0.1:5089 (the PWA is served from the same port) and paste the token from squeakr token when it asks you to pair.

Coming from AgentVoice? One command moves any install — npm, .deb/.rpm or a clone — with its config, keys, pairing token (paired devices keep working), history, logs and background service:

curl -fsSL https://raw.githubusercontent.com/dixonSolutions/Squeakr/main/scripts/migrate-to-squeakr.sh | bash -s -- --dry-run   # see the plan
curl -fsSL https://raw.githubusercontent.com/dixonSolutions/Squeakr/main/scripts/migrate-to-squeakr.sh | bash

On npm the same is npm install -g squeakr && squeakr upgrade-from-agentvoice, or agentvoice migrate-to-squeakr from the last AgentVoice release (0.1.6). It moves ~/.agentvoice to ~/.squeakr (leaving a symlink), replaces the agentvoice service, moves an apt/dnf source to the new URL (GitHub Pages does not redirect it) and removes the old package. Details: docs/45.

Moving from a clone? squeakr migrate ~/Projects/Squeakr carries its config.json and .env (keys and pairing token included, written 0600, never printed) into ~/.squeakr in one step; --with-data brings the job history too, and --dry-run shows what would move. It starts nothing — restart the service (squeakr restart) to load what it carried.

Everything the bridge writes — config.json, data/state.db, logs — stays in that home directory, so npm update -g squeakr never touches your state. Run squeakr from a directory that already has a config.json (a repo checkout, say) and it uses that directory instead.

The default configuration is local-only (the local hosting provider), uses Codex, and discovers immediate Git repositories under ~/Projects. Add nested project containers to settings.projectDiscovery.hotPaths when needed; no hand-maintained project list is required. Requires Node 20+ and one of the agent CLIs — cursor-agent, codex, claude, or codewhale — on your PATH.

Install from apt / dnf

Signed repositories for amd64 and arm64 are published at https://dixonsolutions.github.io/Squeakr/ — upgrades then arrive with the rest of your system (apt upgrade / dnf upgrade).

Debian / Ubuntu

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://dixonsolutions.github.io/Squeakr/squeakr.asc -o /etc/apt/keyrings/squeakr.asc
sudo curl -fsSL https://dixonsolutions.github.io/Squeakr/apt/squeakr.sources -o /etc/apt/sources.list.d/squeakr.sources
sudo apt update && sudo apt install squeakr

Fedora / RHEL

sudo curl -fsSL https://dixonsolutions.github.io/Squeakr/rpm/squeakr.repo -o /etc/yum.repos.d/squeakr.repo
sudo dnf install squeakr

Both enable Squeakr as a background user service out of the box; then run squeakr setup, and loginctl enable-linger "$USER" to keep it running after logout. See docs/43 for details.

The `squeakr` command

Booting the bridge is only the default. The same command manages the install:

squeakr status          # install, version, service, port, health, public URL — one screen
squeakr doctor          # Node, native binding, config, agent CLI + sign-in, port, service, hosting
squeakr service install --now   # (re)install the background service — npm -g and .deb/.rpm already did
squeakr service uninstall       # stop and remove it, e.g. before npm uninstall -g
squeakr restart         # bounce the service
squeakr logs -f         # follow the service journal (or the session log file)
squeakr logs --list     # every session log and voice transcript on disk
squeakr pipe --mic      # talk to the agent from this terminal, no phone needed
squeakr update          # rebase a clone, or npm-install a newer package
squeakr token --new     # rotate the pairing token
squeakr migrate <path>  # carry a clone's config + keys into this install
squeakr add --this-dir   # register the directory you are in as a project
squeakr local --this-dir # throwaway bridge + web client for just this directory, logs in the terminal
squeakr <command> --help   # just that command's options

Speech reaches the agent in turns by default — wake phrase, then VAD, then one whole request — and that is the recommended mode. A direct audio stream is also available, from the phone (Config → Listening & controls → Input mode) or from anything that produces PCM: the bridge cuts it at your pauses and hands each piece to the agent as you talk (docs/41):

arecord -f S16_LE -r 16000 -c 1 -t raw | squeakr pipe

Channels make Discord, Telegram, Slack and WhatsApp a way in too: call the bot in a Discord voice channel and talk to the agent, send it a voice message on Telegram or WhatsApp, or tag it (@Squeakr sessions, default 2, config tts openai) to manage sessions and settings from any chat (docs/44):

squeakr channel enable discord && squeakr channel allow discord <your id>

Every bridge run writes a date-named session log and every voice session a transcript under <home>/logs/, gzipped as they pile up (docs/42).

status is the one to reach for first. It reports how Squeakr was installed and therefore how it updates, the version (branch and drift for a clone, the registry's latest for an npm install), whether the service is running and since when, the port it is listening on and where that port came from, what /healthz says, and whether a pairing token is configured — never the token itself. Add --json for machine output. It exits 1 when the bridge is not answering, so squeakr status >/dev/null works as a liveness probe.

update follows the install rather than guessing: a clone runs scripts/update.sh (pass --stash to carry local changes across the rebase), an npm install runs npm install -g squeakr@latest (without -g for a project dependency), an npx run tells you to start it with @latest, and a .deb / .rpm install prints the apt / dnf command instead of fighting the package manager.

Full reference: docs/35-cli.md.

Quick start (dev)

cp config.example.json config.json
cp .env.example .env   # set APP_TOKEN + AWS IAM keys
npm install
npm run dev

Open the web URL shown in the terminal (unified port in test mode). The example uses Codex with the workspace sandbox, no Tailscale or public hosting, and automatically picks up Git repositories directly under ~/Projects.

Host on Windows (one-command setup)

Prerequisites: Node.js 20 LTS, Git, and one agent CLI on PATH — cursor-agent, codex, claude or codewhale.

# 1. Clone the repo
git clone https://github.com/dixonSolutions/Squeakr.git
cd Squeakr
# Formerly Cursor-Voice — see docs/26-rename-agentvoice.md

# 2. Run setup — installs Tailscale, builds the project, creates .env,
#    installs a Windows Service (NSSM), and configures tailscale serve.
#    Run in an elevated (Administrator) PowerShell terminal.
.\scripts\setup.ps1

After setup, the script prints your APP_TOKEN. Enter it in the PWA settings screen.

After initial setup:

# Rebuild and restart after code changes
.\scripts\restart.ps1

# Diagnose connectivity issues
.\scripts\doctor.ps1

Tailscale required. The setup script installs Tailscale via winget if it is not present. After installation, sign in to Tailscale and enable HTTPS Certificates in the Tailscale admin console to get a trusted HTTPS URL.

Host on Linux (one-command setup)

Prerequisites: Node.js 20 LTS, Git, and one agent CLI on PATH — cursor-agent, codex, claude or codewhale.

# 1. Clone the repo
git clone https://github.com/dixonSolutions/Squeakr.git
cd Squeakr
# Formerly Cursor-Voice — see docs/26-rename-agentvoice.md

# 2. Build, then run the setup wizard (`squeakr setup`): agent CLI and
#    projects, then — if you want it — a systemd user service and hosting
#    (e.g. Tailscale). `--local` skips the service; `--hosting=tailscale` picks it.
bash scripts/setup.sh

After initial setup:

# Rebuild and restart after code changes
bash scripts/restart.sh

# Diagnose connectivity issues
bash scripts/doctor.sh

Already hosted manually? Install the systemd user service without re-running full setup:

bash scripts/install-systemd.sh

Local development vs. the production host:

The two run on separate ports, so they never collide and can run side by side:

	Command	Run profile	Bridge port
Dev (hot reload)	`npm run dev`	`test` (forced when `NODE_ENV=development`)	`5089` (loopback)
Host (background service)	`npm run start:service`	`serve` (from `config.json`)	`8787` (Tailscale)

# Hot-reload dev server. Open http://localhost:4200 — /api + /ws proxy to :5089.
npm run dev

# Manage the long-running production host service (independent of dev):
npm run stop            # stop the host service + its rebuild watcher, free :8787
npm run start:service   # start the host service back up (health-checked)

config.json → settings.runMode controls the host only. npm run dev always uses the test profile (port runModes.test.backendPort, default 5089), regardless of runMode.

Documentation

Full design in docs/ — start with docs/README.md.

Doc	Topic
`02-architecture.md`	System architecture
`06-voice-audio-webrtc.md`	STT, TTS, VAD, wake words
`16-mcp-server-agent-as-brain.md`	Default voice workflow (the agent as the brain)
`11-mcp-tool-surface.md`	MCP tool inventory
`20-native-callkit-shell.md`	CallKit native app + push notifications
`23-multi-agent-client.md`	Cursor / Codex / Claude Code / Codewhale CLI setup
`24-agent-providers.md`	In-app auth, live model selection (per-model effort / fast from each CLI), generic MCP tools
`25-hosting-providers.md`	Tailscale, Cloudflare, ngrok, Dev Tunnels, LAN, manual
`33-permissions-and-prompt-relay.md`	Permission modes per CLI, permission prompts and sudo passwords relayed to the phone
`35-cli.md`	The `squeakr` management CLI
`36-disconnect-and-background-work.md`	Design: disconnect policy, unattended work, surviving bridge restarts
`37-session-directory-and-inject.md`	Design: list running sessions and inject into them by voice
`38-system-packages.md`	Design: .deb / .rpm packages and a system install mode
`39-config-ui-and-narration-cleanup.md`	Config screen audit and bridge narration toggles + templates
`40-prompts-orb-and-permissions.md`	Design: prompts read aloud, ask tools and tool overlap, orb working state, remembered mic permission
`41-audio-stream-pipe.md`	Direct audio stream input — the phone's stream mode and `squeakr pipe`
`42-logging.md`	Session log files, voice transcripts, gzip rollover, `squeakr logs`
`45-rename-squeakr.md`	AgentVoice → Squeakr, and moving an install over
`26-rename-agentvoice.md`	Cursor Voice → AgentVoice rename notes

Stack

Bridge: Node.js 20+, TypeScript, Fastify, MCP SDK, SQLite
Web app: Angular PWA + vanilla TS voice modules (Vosk, Silero VAD)
Voice I/O: pluggable STT/TTS chains — browser, self-hosted Whisper / Kokoro, or cloud providers (see docs/29 and docs/30)
Reasoning: the active agent CLI (agent_native) or Bedrock Claude (llm_intelligence)
Executor: Cursor, Codex, Claude Code, or Codewhale CLI (settings.agentClient, see docs/24-agent-providers.md)
Network: Tailscale by default; Cloudflare Tunnel, ngrok, Azure Dev Tunnels, LAN, or manual (see docs/25-hosting-providers.md)

Configuration

.env — APP_TOKEN, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
config.json — projects, wake words, input mode, workflow, logging, operational settings

See docs/07-data-and-deployment.md.

iPhone PWA (Vosk wake + STT + TTS) │ /ws/intelligence (app token) ▼ Bridge (Node/TS) ── VoiceTurnQueue ── MCP /mcp ──► voice agent (agent CLI) │ │ │ ▼ spawn_agent └──────────────────────────────────────► agent CLI workers → git

curl -fsSL https://raw.githubusercontent.com/dixonSolutions/Squeakr/main/scripts/migrate-to-squeakr.sh | bash -s -- --dry-run # see the plan curl -fsSL https://raw.githubusercontent.com/dixonSolutions/Squeakr/main/scripts/migrate-to-squeakr.sh | bash

sudo install -d -m 0755 /etc/apt/keyrings sudo curl -fsSL https://dixonsolutions.github.io/Squeakr/squeakr.asc -o /etc/apt/keyrings/squeakr.asc sudo curl -fsSL https://dixonsolutions.github.io/Squeakr/apt/squeakr.sources -o /etc/apt/sources.list.d/squeakr.sources sudo apt update && sudo apt install squeakr

squeakr status # install, version, service, port, health, public URL — one screen squeakr doctor # Node, native binding, config, agent CLI + sign-in, port, service, hosting squeakr service install --now # (re)install the background service — npm -g and .deb/.rpm already did squeakr service uninstall # stop and remove it, e.g. before npm uninstall -g squeakr restart # bounce the service squeakr logs -f # follow the service journal (or the session log file) squeakr logs --list # every session log and voice transcript on disk squeakr pipe --mic # talk to the agent from this terminal, no phone needed squeakr update # rebase a clone, or npm-install a newer package squeakr token --new # rotate the pairing token squeakr migrate <path> # carry a clone's config + keys into this install squeakr add --this-dir # register the directory you are in as a project squeakr local --this-dir # throwaway bridge + web client for just this directory, logs in the terminal squeakr <command> --help # just that command's options

# 1. Clone the repo git clone https://github.com/dixonSolutions/Squeakr.git cd Squeakr # Formerly Cursor-Voice — see docs/26-rename-agentvoice.md # 2. Run setup — installs Tailscale, builds the project, creates .env, # installs a Windows Service (NSSM), and configures tailscale serve. # Run in an elevated (Administrator) PowerShell terminal. .\scripts\setup.ps1

# 1. Clone the repo git clone https://github.com/dixonSolutions/Squeakr.git cd Squeakr # Formerly Cursor-Voice — see docs/26-rename-agentvoice.md # 2. Build, then run the setup wizard (`squeakr setup`): agent CLI and # projects, then — if you want it — a systemd user service and hosting # (e.g. Tailscale). `--local` skips the service; `--hosting=tailscale` picks it. bash scripts/setup.sh

Command

Run profile

Bridge port

Dev (hot reload)

npm run dev

test (forced when NODE_ENV=development)

5089 (loopback)

Host (background service)

npm run start:service

serve (from config.json)

8787 (Tailscale)

# Hot-reload dev server. Open http://localhost:4200 — /api + /ws proxy to :5089. npm run dev # Manage the long-running production host service (independent of dev): npm run stop # stop the host service + its rebuild watcher, free :8787 npm run start:service # start the host service back up (health-checked)