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:
# 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.runModecontrols the host only.npm run devalways uses thetestprofile (portrunModes.test.backendPort, default5089), regardless ofrunMode.
Documentation
Full design in docs/ — start with docs/README.md.
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, seedocs/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_KEYconfig.json— projects, wake words, input mode, workflow, logging, operational settings
