voxa-code 0.1.0__tar.gz

voxa_code-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Voxa (Ti)
+
+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.

voxa_code-0.1.0/MANIFEST.in

@@ -0,0 +1,14 @@
+graft static
+graft server
+include README.md
+include LICENSE
+include requirements.txt
+prune tests
+prune ios
+prune web
+prune docs
+prune deploy
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude *.so
+global-exclude .DS_Store

voxa_code-0.1.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: voxa-code
+Version: 0.1.0
+Summary: Hands-free voice operator for Claude Code
+Author-email: Ti <voxa@voxa.space>
+License: MIT
+Project-URL: Homepage, https://voxa.space
+Project-URL: Repository, https://github.com/Ti-03/voxa
+Project-URL: Issues, https://github.com/Ti-03/voxa/issues
+Keywords: claude,claude-code,voice,cli,agent,gemini
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: websockets>=12
+Requires-Dist: google-genai>=0.3
+Requires-Dist: claude-agent-sdk>=0.1
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyjwt[crypto]>=2.8
+Requires-Dist: httpx[http2]>=0.27
+Requires-Dist: qrcode>=7.4
+Requires-Dist: cbor2>=5.6
+Requires-Dist: pyobjc-framework-Quartz>=10; sys_platform == "darwin"
+Requires-Dist: pyobjc-framework-ApplicationServices>=10; sys_platform == "darwin"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Dynamic: license-file
+
+# Voxa
+
+Voxa lets you call into your laptop from a phone browser, talk to a Gemini Live
+"operator," and have it drive Claude Code by voice.
+
+**MVP scope (drive mode only):** pick a working directory by voice, send spoken
+instructions, hear Claude's final result read back. Attach mode, voice
+folder-browsing, and barge-in interruption are V2 backlog items (see
+`docs/superpowers/specs/2026-06-27-loop-design.md` and
+`docs/superpowers/plans/2026-06-27-loop-mvp.md`).
+
+---
+
+## Prerequisites
+
+- **Python 3.11+** on the laptop.
+- **Tailscale** installed and logged in on both the laptop and the phone (free
+  personal plan is fine). The phone must be on the same tailnet as the laptop,
+  or MagicDNS must be enabled.
+- **A Gemini API key** from [Google AI Studio](https://aistudio.google.com/live)
+  with Gemini Live access.
+- **Claude Code logged in** on the laptop (`claude` CLI authenticated). The
+  agent SDK reuses your existing Claude Code credentials; no separate
+  `ANTHROPIC_API_KEY` is needed unless you prefer to supply one.
+
+---
+
+## Quickstart
+
+Install Voxa on the laptop you want to control with one command.
+
+**macOS / Linux:**
+
+```bash
+curl -fsSL https://voxa.space/install.sh | sh
+```
+
+**Windows (PowerShell):**
+
+```powershell
+irm https://voxa.space/install.ps1 | iex
+```
+
+Prefer a package runner? These work on any OS:
+
+```bash
+npx voxa-code            # Node users
+uvx voxa-code            # Python users (or: pipx install voxa-code)
+```
+
+Then start it:
+
+```bash
+voxa
+```
+
+Voxa is zero-config by default: it uses the hosted relay, so there are no API
+keys to set up. `voxa` starts the server and prints a pairing QR code. Scan it
+with the Voxa phone app (or open the printed URL in your phone browser) to
+connect.
+
+---
+
+## Develop from source
+
+Contributors who want to hack on Voxa can run it from a checkout instead of the
+published package.
+
+### 1. Create and activate the virtual environment
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+```
+
+### 2. Configure secrets
+
+```bash
+cp .env.example .env
+```
+
+Open `.env` and fill in:
+
+| Key | Value |
+|---|---|
+| `GEMINI_API_KEY` | Your Google AI Studio key |
+| `VOXA_AUTH_TOKEN` | Any random secret string (protects the WebSocket endpoint on your tailnet) |
+
+`GEMINI_LIVE_MODEL`, `VOXA_HOST`, and `VOXA_PORT` have sensible defaults and
+can be left as-is.
+
+### 3. Start the server
+
+```bash
+bash scripts/serve.sh
+```
+
+The script:
+1. Starts the Voxa FastAPI server on `127.0.0.1:8787` (or `$VOXA_PORT`).
+2. Calls `tailscale serve` to expose it over HTTPS on your tailnet (required
+   because the phone browser needs a secure context for microphone access).
+3. Prints the full HTTPS URL including your auth token.
+
+### 4. Connect from the phone
+
+Open the printed URL on your phone browser. Tap **Connect**, then speak.
+
+---
+
+## Architecture (brief)
+
+```
+Phone browser (static/)
+    |  HTTPS WebSocket (auth token required)
+    v
+FastAPI server (server/app.py)
+    |  audio bytes (16 kHz PCM)
+    v
+GeminiOperator (server/gemini_operator.py)  <-->  Gemini Live API
+    |  tool calls (start_claude_session, send_to_claude, …)
+    v
+Orchestrator (server/orchestrator.py)
+    |
+    v
+ClaudeController (server/claude_controller.py)  -->  Claude Code (agent SDK, bypassPermissions)
+```
+
+Config is loaded from `.env` via `server/config.py`.
+
+---
+
+## Running the test suite
+
+```bash
+.venv/bin/python -m pytest -v
+```
+
+Expected: 22 tests pass, no warnings.
+
+---
+
+## Manual end-to-end smoke test
+
+The smoke test requires a real phone, real Tailscale connectivity, and real API
+keys. Run it against a scratch directory, not a real project.
+
+**Before you start:**
+- `.env` is fully filled in (real `GEMINI_API_KEY` and `VOXA_AUTH_TOKEN`).
+- Tailscale is running on both the laptop and the phone.
+- Claude Code is logged in on the laptop.
+
+**Procedure:**
+
+1. Open a terminal on the laptop and run:
+   ```bash
+   bash scripts/serve.sh
+   ```
+   Wait for the line `Voxa is live. On your phone open: https://...`
+
+2. Copy the printed HTTPS URL (it already includes `?token=...`).
+
+3. On the phone, open the URL in Safari or Chrome. You should see the Voxa
+   interface. Grant microphone permission when prompted.
+
+4. Tap **Connect**. The button should change state to indicate an active
+   session.
+
+5. Speak: "Start a session in `/tmp/loop-smoke` and create a file called
+   `hello.txt` that says hi."
+
+6. **Verify:**
+   - Gemini acknowledges the instruction verbally (you hear a response through
+     the phone speaker).
+   - On the laptop terminal you see Claude Code start with `bypassPermissions`
+     active (no permission prompts appear).
+   - After Claude finishes, `/tmp/loop-smoke/hello.txt` exists on the laptop
+     and contains `hi`.
+   - Gemini speaks the final result back to you.
+
+7. To stop: press Ctrl-C in the laptop terminal. The `trap` in `serve.sh` will
+   kill the server and tear down `tailscale serve`.
+
+**Warning:** Use a throwaway scratch directory (like `/tmp/loop-smoke`) for
+your first smoke test. Claude Code runs with `bypassPermissions`, so it will
+write files without asking.

voxa_code-0.1.0/README.md

@@ -0,0 +1,185 @@
+# Voxa
+
+Voxa lets you call into your laptop from a phone browser, talk to a Gemini Live
+"operator," and have it drive Claude Code by voice.
+
+**MVP scope (drive mode only):** pick a working directory by voice, send spoken
+instructions, hear Claude's final result read back. Attach mode, voice
+folder-browsing, and barge-in interruption are V2 backlog items (see
+`docs/superpowers/specs/2026-06-27-loop-design.md` and
+`docs/superpowers/plans/2026-06-27-loop-mvp.md`).
+
+---
+
+## Prerequisites
+
+- **Python 3.11+** on the laptop.
+- **Tailscale** installed and logged in on both the laptop and the phone (free
+  personal plan is fine). The phone must be on the same tailnet as the laptop,
+  or MagicDNS must be enabled.
+- **A Gemini API key** from [Google AI Studio](https://aistudio.google.com/live)
+  with Gemini Live access.
+- **Claude Code logged in** on the laptop (`claude` CLI authenticated). The
+  agent SDK reuses your existing Claude Code credentials; no separate
+  `ANTHROPIC_API_KEY` is needed unless you prefer to supply one.
+
+---
+
+## Quickstart
+
+Install Voxa on the laptop you want to control with one command.
+
+**macOS / Linux:**
+
+```bash
+curl -fsSL https://voxa.space/install.sh | sh
+```
+
+**Windows (PowerShell):**
+
+```powershell
+irm https://voxa.space/install.ps1 | iex
+```
+
+Prefer a package runner? These work on any OS:
+
+```bash
+npx voxa-code            # Node users
+uvx voxa-code            # Python users (or: pipx install voxa-code)
+```
+
+Then start it:
+
+```bash
+voxa
+```
+
+Voxa is zero-config by default: it uses the hosted relay, so there are no API
+keys to set up. `voxa` starts the server and prints a pairing QR code. Scan it
+with the Voxa phone app (or open the printed URL in your phone browser) to
+connect.
+
+---
+
+## Develop from source
+
+Contributors who want to hack on Voxa can run it from a checkout instead of the
+published package.
+
+### 1. Create and activate the virtual environment
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+```
+
+### 2. Configure secrets
+
+```bash
+cp .env.example .env
+```
+
+Open `.env` and fill in:
+
+| Key | Value |
+|---|---|
+| `GEMINI_API_KEY` | Your Google AI Studio key |
+| `VOXA_AUTH_TOKEN` | Any random secret string (protects the WebSocket endpoint on your tailnet) |
+
+`GEMINI_LIVE_MODEL`, `VOXA_HOST`, and `VOXA_PORT` have sensible defaults and
+can be left as-is.
+
+### 3. Start the server
+
+```bash
+bash scripts/serve.sh
+```
+
+The script:
+1. Starts the Voxa FastAPI server on `127.0.0.1:8787` (or `$VOXA_PORT`).
+2. Calls `tailscale serve` to expose it over HTTPS on your tailnet (required
+   because the phone browser needs a secure context for microphone access).
+3. Prints the full HTTPS URL including your auth token.
+
+### 4. Connect from the phone
+
+Open the printed URL on your phone browser. Tap **Connect**, then speak.
+
+---
+
+## Architecture (brief)
+
+```
+Phone browser (static/)
+    |  HTTPS WebSocket (auth token required)
+    v
+FastAPI server (server/app.py)
+    |  audio bytes (16 kHz PCM)
+    v
+GeminiOperator (server/gemini_operator.py)  <-->  Gemini Live API
+    |  tool calls (start_claude_session, send_to_claude, …)
+    v
+Orchestrator (server/orchestrator.py)
+    |
+    v
+ClaudeController (server/claude_controller.py)  -->  Claude Code (agent SDK, bypassPermissions)
+```
+
+Config is loaded from `.env` via `server/config.py`.
+
+---
+
+## Running the test suite
+
+```bash
+.venv/bin/python -m pytest -v
+```
+
+Expected: 22 tests pass, no warnings.
+
+---
+
+## Manual end-to-end smoke test
+
+The smoke test requires a real phone, real Tailscale connectivity, and real API
+keys. Run it against a scratch directory, not a real project.
+
+**Before you start:**
+- `.env` is fully filled in (real `GEMINI_API_KEY` and `VOXA_AUTH_TOKEN`).
+- Tailscale is running on both the laptop and the phone.
+- Claude Code is logged in on the laptop.
+
+**Procedure:**
+
+1. Open a terminal on the laptop and run:
+   ```bash
+   bash scripts/serve.sh
+   ```
+   Wait for the line `Voxa is live. On your phone open: https://...`
+
+2. Copy the printed HTTPS URL (it already includes `?token=...`).
+
+3. On the phone, open the URL in Safari or Chrome. You should see the Voxa
+   interface. Grant microphone permission when prompted.
+
+4. Tap **Connect**. The button should change state to indicate an active
+   session.
+
+5. Speak: "Start a session in `/tmp/loop-smoke` and create a file called
+   `hello.txt` that says hi."
+
+6. **Verify:**
+   - Gemini acknowledges the instruction verbally (you hear a response through
+     the phone speaker).
+   - On the laptop terminal you see Claude Code start with `bypassPermissions`
+     active (no permission prompts appear).
+   - After Claude finishes, `/tmp/loop-smoke/hello.txt` exists on the laptop
+     and contains `hi`.
+   - Gemini speaks the final result back to you.
+
+7. To stop: press Ctrl-C in the laptop terminal. The `trap` in `serve.sh` will
+   kill the server and tear down `tailscale serve`.
+
+**Warning:** Use a throwaway scratch directory (like `/tmp/loop-smoke`) for
+your first smoke test. Claude Code runs with `bypassPermissions`, so it will
+write files without asking.

voxa_code-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "voxa-code"
+version = "0.1.0"
+description = "Hands-free voice operator for Claude Code"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Ti", email = "voxa@voxa.space" }]
+keywords = ["claude", "claude-code", "voice", "cli", "agent", "gemini"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.29",
+    "websockets>=12",
+    "google-genai>=0.3",
+    "claude-agent-sdk>=0.1",
+    "python-dotenv>=1.0",
+    "pyjwt[crypto]>=2.8",
+    "httpx[http2]>=0.27",
+    "qrcode>=7.4",
+    "cbor2>=5.6",
+    "pyobjc-framework-Quartz>=10; sys_platform == 'darwin'",
+    "pyobjc-framework-ApplicationServices>=10; sys_platform == 'darwin'",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://voxa.space"
+Repository = "https://github.com/Ti-03/voxa"
+Issues = "https://github.com/Ti-03/voxa/issues"
+
+[project.scripts]
+voxa = "server.cli:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+# `static/` ships as a top-level data tree so that, once installed, it sits as a
+# sibling of the `server` package (site-packages/static/). server/app.py resolves
+# it via `Path(__file__).resolve().parent.parent / "static"`, i.e. relative to the
+# installed package, so it must live next to `server`, not inside it.
+packages = ["server", "static"]
+include-package-data = true
+
+[tool.setuptools.package-data]
+static = ["**/*"]
+# Ship Apple's StoreKit root cert so purchase verification works out of the box.
+server = ["certs/*.pem"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+filterwarnings = [
+    # Third-party deprecation from Starlette's TestClient (recommends httpx2); not our code.
+    "ignore:Using `httpx` with `starlette.testclient` is deprecated",
+]

voxa_code-0.1.0/requirements.txt

@@ -0,0 +1,12 @@
+fastapi>=0.110
+uvicorn[standard]>=0.29
+websockets>=12
+google-genai>=0.3
+claude-agent-sdk>=0.1
+python-dotenv>=1.0
+pyjwt[crypto]>=2.8
+httpx[http2]>=0.27
+qrcode>=7.4
+cbor2>=5.6
+pyobjc-framework-Quartz>=10; sys_platform == "darwin"
+pyobjc-framework-ApplicationServices>=10; sys_platform == "darwin"

voxa_code-0.1.0/server/apns.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import json
+import logging
+
+import httpx
+import jwt
+
+logger = logging.getLogger(__name__)
+
+
+def build_apns_jwt(key_pem: str, key_id: str, team_id: str, issued_at: int) -> str:
+    return jwt.encode(
+        {"iss": team_id, "iat": issued_at},
+        key_pem,
+        algorithm="ES256",
+        headers={"alg": "ES256", "kid": key_id},
+    )
+
+
+def build_voip_payload(call_id: str, summary: str) -> dict:
+    return {"call_id": call_id, "summary": summary, "aps": {"content-available": 1}}
+
+
+def build_cancel_payload(call_id: str) -> dict:
+    return {"call_id": call_id, "type": "cancel", "aps": {"content-available": 1}}
+
+
+class ApnsClient:
+    """Sends VoIP pushes via APNs HTTP/2. One per server process."""
+
+    PROD_HOST = "https://api.push.apple.com"
+    SANDBOX_HOST = "https://api.sandbox.push.apple.com"
+
+    def __init__(self, config, now_fn=None):
+        self._cfg = config
+        # Xcode/dev-signed builds get sandbox push tokens, which only work
+        # against the sandbox host; TestFlight/App Store builds use production.
+        self._host = self.SANDBOX_HOST if getattr(config, "apns_sandbox", False) else self.PROD_HOST
+        import time
+        self._now = now_fn or (lambda: int(time.time()))
+        self._jwt = ""
+        self._jwt_at = 0
+
+    def _token(self) -> str:
+        now = self._now()
+        if not self._jwt or now - self._jwt_at > 50 * 60:
+            # Prefer the key contents (set as a secret on container hosts); fall
+            # back to a file path for local/dev use.
+            key_pem = getattr(self._cfg, "apns_key", "") or open(self._cfg.apns_key_path).read()
+            self._jwt = build_apns_jwt(
+                key_pem, self._cfg.apns_key_id, self._cfg.apns_team_id, now
+            )
+            self._jwt_at = now
+        return self._jwt
+
+    async def send_voip(self, device_token: str, call_id: str, summary: str) -> bool | int:
+        """Send a VoIP ring. Returns True on success, or the HTTP status code on
+        failure (so the caller can prune a 410 Gone / dead token)."""
+        url = f"{self._host}/3/device/{device_token}"
+        headers = {
+            "apns-topic": f"{self._cfg.apns_bundle_id}.voip",
+            "apns-push-type": "voip",
+            "apns-priority": "10",
+            "authorization": f"bearer {self._token()}",
+        }
+        payload = build_voip_payload(call_id, summary)
+        async with httpx.AsyncClient(http2=True, timeout=10) as client:
+            resp = await client.post(url, headers=headers, content=json.dumps(payload))
+            if resp.status_code != 200:
+                # 410 = the token is dead (app deleted/reinstalled); other codes are
+                # transient/config. Log the reason so silent no-rings are diagnosable.
+                logger.warning("APNs voip push failed: status=%s body=%s token=%s",
+                               resp.status_code, resp.text[:200], device_token[:8])
+                return resp.status_code
+            return True
+
+    async def send_voip_cancel(self, device_token: str, call_id: str) -> bool:
+        url = f"{self._host}/3/device/{device_token}"
+        headers = {
+            "apns-topic": f"{self._cfg.apns_bundle_id}.voip",
+            "apns-push-type": "voip",
+            "apns-priority": "10",
+            "authorization": f"bearer {self._token()}",
+        }
+        payload = build_cancel_payload(call_id)
+        async with httpx.AsyncClient(http2=True, timeout=10) as client:
+            resp = await client.post(url, headers=headers, content=json.dumps(payload))
+            return resp.status_code == 200