meldivo 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amir Rouhollahi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# meldivo
+
+**Always-on local voice hub for coding agents.** Install it once, and talk by
+voice to your [Pi](https://pi.dev), [OpenCode](https://opencode.ai), and
+[Claude Code](https://claude.com/claude-code) sessions from any browser or
+phone. Speech recognition and speech synthesis run locally on your machine:
+no cloud speech API, no API keys for speech, no extra LLM.
+
+```bash
+npm i -g meldivo
+meldivo start
+```
+
+`meldivo start` installs a user service that keeps the hub running in the
+background, then prints a local link and a QR code:
+
+```text
+http://127.0.0.1:4100/#token=...
+```
+
+Open the link (or scan the QR code) to see every Pi, OpenCode, and Claude
+Code session on the machine, plus a "new chat" tile for each installed agent.
+Tap any tile to start talking.
+
+## Features
+
+- **One hub for every session.** The hub page lists your Pi, OpenCode, and
+  Claude Code sessions automatically, found from their own session files —
+  no plugins or extensions to install in each agent.
+- **Hands-free conversation.** Your speech becomes a turn in the chosen
+  session, run headlessly with that session's own model and credentials.
+  Replies are spoken back to you.
+- **Safe alongside your terminal.** If a session is already open in a
+  terminal, talking to it by voice continues it as a fork, so the voice
+  copy never conflicts with what you're typing.
+- **Local, private speech.** Speech-to-text uses NVIDIA Parakeet TDT 0.6B v3
+  and text-to-speech uses Kokoro v1.0, both running on the CPU through
+  [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx). Audio never leaves
+  your machine unless you turn on phone access.
+- **Phone and tablet access.** `meldivo remote` (or the hub's "Phone access"
+  panel) publishes the hub over HTTPS through Tailscale, a Cloudflare
+  tunnel, or your own certificate, and shows a QR code to scan.
+- **Runs in the background.** A user service (systemd on Linux, launchd on
+  macOS) starts the hub on login and keeps it running. Models download once
+  on first use.
+- **Secure by default.** The server listens on `127.0.0.1` only, and the
+  whole hub is protected by a random token embedded in its link.
+
+## Requirements
+
+- Node.js 22 or later
+- macOS or Linux (x64 or arm64)
+- At least one of: Pi, OpenCode, Claude Code
+- About 650 MB of disk space for the speech models, downloaded on first use
+
+## Supported agents
+
+| Agent | Sessions found from | "Open in terminal" | Tool approvals |
+|---|---|---|---|
+| Pi | Pi's own session files in the home folder | A voice turn continues the session as a fork, leaving the terminal session untouched | No approval step; a denied action is announced |
+| OpenCode | OpenCode's session files | A voice turn continues the session as a fork, leaving the terminal session untouched | Headless runs auto-reject actions that need approval |
+| Claude Code | Claude Code's session files | A voice turn continues the session as a fork, leaving the terminal session untouched | Runs with `--permission-mode acceptEdits` |
+
+Pi is listed first on the hub page, since it's the reference agent for this
+project.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `meldivo start` | Install (if needed) and start the background service, then print the hub link and QR code. |
+| `meldivo stop` | Stop the background service. |
+| `meldivo status` | Show whether the service is running and its listening address. |
+| `meldivo open [--browser]` | Print the hub link, optionally opening it in a browser. |
+| `meldivo remote` | Set up phone/tablet access over HTTPS. |
+| `meldivo remote tailscale` | Publish the hub over Tailscale. |
+| `meldivo remote cloudflare` | Publish the hub through a Cloudflare quick tunnel. |
+| `meldivo remote certificate` | Publish the hub over HTTPS using your own certificate. |
+| `meldivo remote stop` | Turn remote access off. |
+| `meldivo logs` | Show the service's recent log output. |
+| `meldivo uninstall [--purge]` | Remove the background service. `--purge` also deletes configuration, models, and logs. |
+| `meldivo --version` | Print the installed version. |
+
+## Using it from a phone or another computer
+
+Browsers only allow microphone access on `localhost` or over HTTPS, so
+another device needs an HTTPS link. Run `meldivo remote`, or open the hub's
+"Phone access" panel, to set one up:
+
+1. **Tailscale**: private to your own devices, works from anywhere.
+2. **Cloudflare quick tunnel**: no account needed, produces a public link
+   protected by its token.
+3. **Your own certificate**: HTTPS on your local network or VPN, for example
+   with `mkcert`.
+
+Whichever option you pick, the link is the same hub link — the whole hub
+becomes reachable from that device, protected by its token. See the
+[remote access guide](docs/remote-access.md) for setup details, including
+how to trust a certificate on iPhone and Android.
+
+## How it works
+
+`meldivo start` installs a user service that runs the hub server on
+`127.0.0.1:4100`. The hub scans each installed agent's session files to list
+recent sessions and shows a "new chat" tile for each installed agent. When
+you talk to a session, the hub runs that agent headlessly for one turn, using
+its own model and credentials; if the session is open in a terminal, the
+turn runs against a fork instead, so the terminal session is never touched.
+Your speech is transcribed locally, sent to the agent as a normal user
+message, and the reply is read aloud with local text-to-speech.
+
+## Configuration
+
+All settings are optional.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `MELDIVO_PORT` | `4100` | Port of the local server (`127.0.0.1` only). |
+| `MELDIVO_HTTPS_PORT` | `4443` | HTTPS port used by the "own certificate" remote option. |
+| `MELDIVO_PUBLIC_URL` | unset | Base URL to print when you run your own reverse proxy. |
+| `MELDIVO_MODELS_DIR` | `~/.cache/meldivo/models` | Location of the downloaded speech models. |
+
+## Files and locations
+
+| Path | Contents |
+|---|---|
+| `~/.config/meldivo/secret` | The hub's shared secret, generated automatically. |
+| `~/.cache/meldivo/models` | Downloaded speech models. |
+| `~/.local/state/meldivo` | Service logs and runtime state. |
+
+## Security notes
+
+The server listens on `127.0.0.1` only; it is never exposed on the network
+unless you explicitly turn on phone access. Every hub link, local or remote,
+embeds a random token, and requests without it are rejected. Treat the hub
+link like a password: anyone who has it can use every session in the hub.
+
+## Uninstall
+
+```bash
+meldivo uninstall --purge
+npm rm -g meldivo
+```
+
+`meldivo uninstall` alone removes the background service but keeps your
+configuration, models, and logs; add `--purge` to remove those too.
+
+## Development
+
+```bash
+npm install
+npm test
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the project layout and
+conventions.
+
+## License
+
+MIT. See [LICENSE](LICENSE). Third-party software and model licenses are
+listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,59 @@
+# Third-Party Notices
+
+meldivo is MIT-licensed, but it uses and can interoperate with software and
+models under their own terms. This file identifies the material dependencies
+and optional components known to this source release. It is not a replacement
+for the complete license text supplied by each dependency.
+
+## Speech runtime
+
+Speech-to-text and text-to-speech run locally via
+[sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx) (`sherpa-onnx-node`).
+
+- [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx/blob/master/LICENSE) — Apache-2.0
+
+Model weights are downloaded on first use and cached under
+`~/.cache/meldivo/models`; they are not committed to this repository.
+
+Speech-to-text:
+
+- [NVIDIA Parakeet TDT 0.6B v3](https://huggingface.co/nvidia/parakeet-tdt-0.6b-v3) — CC-BY-4.0
+
+Text-to-speech:
+
+- [Kokoro v1.0](https://huggingface.co/hexgrad/Kokoro-82M) — Apache-2.0
+
+## Included web runtime components
+
+The web application uses voice-activity detection assets copied at build time
+from `@ricky0123/vad-web`, which bundles Silero VAD and runs on ONNX Runtime
+Web.
+
+- [@ricky0123/vad-web](https://www.npmjs.com/package/@ricky0123/vad-web) — ISC
+- [Silero VAD](https://github.com/snakers4/silero-vad/blob/master/LICENSE) — MIT
+- [ONNX Runtime Web](https://github.com/microsoft/onnxruntime/blob/main/LICENSE) — MIT
+
+## JavaScript and TypeScript dependencies
+
+The exact dependency tree and resolved versions are recorded in
+[`package-lock.json`](package-lock.json). License metadata and license files
+are supplied by the respective npm packages. The main direct dependencies are:
+
+- [Express](https://www.npmjs.com/package/express) — MIT
+- [sherpa-onnx-node](https://www.npmjs.com/package/sherpa-onnx-node) — Apache-2.0
+- [qrcode](https://www.npmjs.com/package/qrcode) — MIT
+- [React](https://www.npmjs.com/package/react) and
+  [React DOM](https://www.npmjs.com/package/react-dom) — MIT
+- [TypeScript](https://www.npmjs.com/package/typescript) — Apache-2.0
+- [Vite](https://www.npmjs.com/package/vite) — MIT
+- [tsx](https://www.npmjs.com/package/tsx) — MIT
+
+Transitive dependencies remain under their original licenses.
+
+## External services and coding harnesses
+
+meldivo drives [Pi](https://pi.dev), [OpenCode](https://opencode.ai), and
+[Claude Code](https://claude.com/claude-code) headlessly, using each
+session's own model, tools, and credentials. None of these agents are
+bundled with meldivo; the user installs them separately, and their terms are
+selected and operated by the user.