- Bun installed for daemon and adapter development.
- Git checkout on
dev. - Optional providers documented in dependencies.md.
- Website development uses the separate site workflow.
Bun runs the daemon and adapter TypeScript directly, without a runtime build step. Link their workspace packages before developing them:
bun installThe runtime workspace packages are local; bun install also resolves the root development
dependencies declared in package.json. It creates
adapters/<host>/node_modules/@echo/shared, which is how each
adapter resolves the shared package it declares instead of reaching up the tree. Skip it
and a registered adapter fails to load. scripts/install.sh runs it for you, and
scripts/install.sh --check reports a missing link as stale.
Run the website tooling from site/, separately from the Bun runtime workspace. Use the Node
version in site/.node-version, then:
cd site
npm ci
npm run devThe site checks are defined in site/package.json and run in
site.yml; the root bun run verify does not run them.
See site/AGENTS.md for content ownership and publishing rules.
Use a non-production port so the installed LaunchAgent on :3246 is not disturbed. Redirect
the config reader with the test/development-only ECHO_CONFIG_FILE path selector:
mkdir -p .scratch
printf '%s\n' '{"PORT":8889,"ECHO_DAEMON_URL":"http://localhost:8889"}' > .scratch/echo-dev-config.json
ECHO_CONFIG_FILE="$PWD/.scratch/echo-dev-config.json" bun run core/server.tsSilent smoke request:
curl -fsS -X POST http://localhost:8889/notify \
-H 'Content-Type: application/json' \
-d '{"message":"dev smoke","voice_enabled":false}'Point Pi (or omp) at the same isolated config:
ECHO_CONFIG_FILE="$PWD/.scratch/echo-dev-config.json" piECHO_CONFIG_FILE="$PWD/.scratch/echo-dev-config.json" bun --watch run core/server.tsIf a provider subprocess hangs, stop the watch process and clear the dev port.
Choose per-agent edge-tts voices by ear with bun scripts/preview-voices.ts before editing core/voices.json. Commands, flags, and the workflow live in voices.md. The script calls edge-tts directly and is not on the runtime request path.
Use local worktrees for isolated feature or release work when you do not want to disturb the
main dev checkout:
mkdir -p .worktrees
git worktree add -b fix/example .worktrees/fix-example origin/dev.worktrees/ is intentionally gitignored. Remove finished worktrees with
git worktree remove .worktrees/<name> and then git worktree prune.
After bun install, bun run verify runs the repository's validation checks. Individual check aliases are defined in
package.json; other script runners follow the
README usage.
bun install # required before bun test - adapters import @echo/shared
bun run verifyThe script definitions in package.json own the individual commands,
including the adapter build list. CI runs the corresponding checks headlessly on every PR
into dev/master and every push to those branches; its steps live in
verify.yml.
The installed LaunchAgent on :3246 serves the operator's real notifications. Stopping it,
retargeting it, overwriting its config, or speaking through it is a live-system incident, not
a test.
tests/e2e-adapters.sh is the safe path. It starts its own core/server.ts on its own port
(ECHO_E2E_PORT, default 8899) with every state path - mute, capture guard, audio cache,
TTS cache, lifecycle log, and VOICES_PATH - redirected through a scratch config file,
while exported copies exist only for inline test assertions. It kills only the pid it started. It refuses to run
if the chosen port is 3246 or if anything is already listening there: it never attaches to a
daemon it does not own. Before sending anything it prints an isolation proof (pid, port,
adapter target, scratch dir).
tests/e2e-adapters.sh # silent - safe anywhere
tests/e2e-adapters.sh --audible # also speaks, on the isolated instance onlytests/e2e-converse.sh applies the same discipline to the voice ask, with two additions of its
own. It starts a second isolated process (the echo-converse coordinator, ECHO_E2E_CONVERSE_PORT,
default 8922) and refuses 32468 as well as 3246. And its recorder and transcriber are
stand-in scripts, so it opens no microphone and needs neither sox nor yap - which is what lets
it run on CI. Silence comes from enabling only say in its own scratch voices.json and
routing it to a no-op executable: an ask
forces voice_enabled on by design, so --audible is the only way to hear it (and the only way
to exercise real synthesis timing in the drain wait). See converse.md.
Every spoken test line begins Echo Test engaged. Beep, boop, bop. so anything audible is
unmistakably a test and never mistaken for a real notification.
lsof -nP -iTCP:8889 | awk 'NR>1 {print $2}' | xargs kill 2>/dev/null || true- If
:8889is busy, choose another dev port. - If
edge-ttsfails,/notifyshould try real synthesis before falling back unless the Edge circuit is already open; inspectattempts[]in the resolution log forphase,reason, and stderr. - If production voice changes, confirm you did not run scripts against
:3246unintentionally.