voice-copilot 0.0.1__tar.gz

voice_copilot-0.0.1/.dockerignore

@@ -0,0 +1,20 @@
+.venv
+.git
+.github
+.vscode
+.idea
+__pycache__
+*.pyc
+*.pyo
+dist
+build
+.pytest_cache
+.ruff_cache
+.mypy_cache
+uv.lock
+.claude
+CLAUDE.md
+docs
+scripts
+tests
+*.egg-info

voice_copilot-0.0.1/.env.example

@@ -0,0 +1,19 @@
+# Copy to .env and fill in the keys you plan to use.
+# Alternatively, store them in the OS keyring through the settings page.
+
+# --- Commentator LLM ---
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=
+# For OpenAI-compatible local servers (Ollama, LM Studio)
+OPENAI_COMPAT_BASE_URL=http://127.0.0.1:11434/v1
+OPENAI_COMPAT_API_KEY=ollama
+
+# --- Cloud STT ---
+DEEPGRAM_API_KEY=
+
+# --- Cloud TTS ---
+ELEVENLABS_API_KEY=
+
+# --- Server ---
+VOICE_COPILOT_HOST=127.0.0.1
+VOICE_COPILOT_PORT=8765

voice_copilot-0.0.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,56 @@
+name: Bug report
+description: Report something that is not working as expected
+title: "bug: "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug. Please remove any API keys, tokens, and private file paths before submitting.
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What happened?
+      placeholder: Voice Copilot...
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Reproduction steps
+      description: How can we reproduce the issue?
+      placeholder: |
+        1. Run `voice-copilot ...`
+        2. Open ...
+        3. See ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Versions and platform details
+      value: |
+        - OS:
+        - Python:
+        - Voice Copilot version or commit:
+        - Target CLI and version:
+        - TTS provider:
+        - STT provider:
+        - Commentator provider:
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs or screenshots
+      description: Paste relevant logs. Redact secrets and tokens.
+      render: text

voice_copilot-0.0.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security report
+    url: mailto:info@conus.vision
+    about: Please report suspected security vulnerabilities privately.

voice_copilot-0.0.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,41 @@
+name: Feature request
+description: Suggest an idea or improvement
+title: "feature: "
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What workflow or pain point should this solve?
+      placeholder: When using Voice Copilot with...
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would you like Voice Copilot to do?
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - CLI adapter
+        - Proxy
+        - Commentator / narration
+        - TTS provider
+        - STT provider
+        - Web UI
+        - Hotkeys / tray
+        - Documentation
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Are there other ways to solve this?

voice_copilot-0.0.1/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Summary
+
+Describe what changed and why.
+
+## Testing
+
+- [ ] `uv run ruff format --check .`
+- [ ] `uv run ruff check .`
+- [ ] `uv run mypy src/voice_copilot`
+- [ ] `uv run pytest`
+
+## Notes
+
+Mention any follow-up work, compatibility concerns, or provider-specific behavior.

voice_copilot-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: ${{ matrix.os }} / Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Type check
+        run: uv run mypy src/voice_copilot
+
+      - name: Test
+        run: uv run pytest

voice_copilot-0.0.1/.gitignore

@@ -0,0 +1,27 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.env
+.env.local
+dist/
+build/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+*.log
+
+# voice-copilot runtime
+~/.voice-copilot/
+logs/
+recordings/
+
+# editor
+.vscode/
+.idea/
+
+# claude code
+.claude/
+.aider*

voice_copilot-0.0.1/CLAUDE.md

@@ -0,0 +1,122 @@
+# CLAUDE.md
+
+Project: **voice-copilot** — open-source voice pair-programmer for LLM CLIs (Claude Code, Codex CLI, Gemini CLI, Aider, …).
+
+## Product idea
+
+The tool sits next to an LLM coding agent and narrates what the agent is doing — decisions taken, files changed, reasoning summarised — as a calm human-voice stream. The user can press a push-to-talk hotkey, ask a question or give a correction, and that message gets injected back into the running agent.
+
+Think: a programmer on a screen-share, talking through what they're doing while their partner can interrupt at any time.
+
+## High-level architecture
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ Browser (popup + settings)          ← localhost:PORT      │
+│   getUserMedia → WebSocket        (mic in)                │
+│   <audio> ← WebSocket             (TTS out)               │
+└──────────────────────────────────────────────────────────┘
+                     ▲  ▲
+                     │  │   WebSocket (events, audio frames)
+                     ▼  ▼
+┌──────────────────────────────────────────────────────────┐
+│ Python server  (FastAPI + uvicorn + asyncio)              │
+│                                                           │
+│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐  │
+│  │ CLI adapter  │──▶│  Event bus   │◀──│ HTTP proxy   │  │
+│  │ (stream-json │   │ (asyncio)    │   │ (mitmproxy)  │  │
+│  │  subprocess) │   └──────┬───────┘   └──────────────┘  │
+│  └──────┬───────┘          │                              │
+│         │                  ▼                              │
+│  stdin  │          ┌───────────────┐                      │
+│  inject │          │ Commentator   │  Haiku/gpt-4o-mini/  │
+│         │          │ (debounce,    │  local ollama        │
+│         │          │  classify,    │                      │
+│         │          │  summarize)   │                      │
+│         │          └──────┬────────┘                      │
+│         │                 ▼                               │
+│         │          ┌───────────────┐                      │
+│         │          │ TTS provider  │  edge-tts / Silero / │
+│         │          │               │  ElevenLabs / OpenAI │
+│         │          └───────────────┘                      │
+│         ▲                                                 │
+│  ┌──────┴───────┐  ┌───────────────┐  ┌───────────────┐  │
+│  │ Dialog mgr   │◀─│ STT provider  │◀─│ Hotkey / Tray │  │
+│  │ (queue,      │  │ (whisper-api/ │  │ (pynput/      │  │
+│  │  /btw, inj.) │  │  f-whisper/   │  │  pystray)     │  │
+│  │              │  │  deepgram)    │  │               │  │
+│  └──────────────┘  └───────────────┘  └───────────────┘  │
+└──────────────────────────────────────────────────────────┘
+```
+
+### Three interception strategies (A first-class, B first-class, C fallback)
+
+- **A. Stream-JSON mode of the target CLI** — e.g. `claude -p --output-format stream-json`, `codex exec --json`. Structured events, reliable, but CLI runs headless (no TUI).
+- **B. HTTP proxy** — mitmproxy sets on `ANTHROPIC_BASE_URL` / `OPENAI_BASE_URL`. Captures the raw SSE including `thinking` blocks. Works alongside interactive TUI.
+- **C. PTY wrapper fallback** — wraps any binary, parses rendered stdout. Low-quality narration but guarantees coverage.
+
+### Injecting voice into a running agent — per-adapter capability
+
+Adapters declare a `QuickAsideCapability`:
+
+1. **native** — CLI supports a built-in "side question" channel (e.g. Claude Code `/btw <q>`). Inject immediately.
+2. **queue** — no native channel; we write the message to subprocess stdin at the next turn boundary (or on hard-interrupt).
+3. **manual** — fully external CLI; we copy the question to the clipboard and show it in the popup so the user pastes it.
+
+### Providers are pluggable
+
+All of **TTS**, **STT**, **commentator LLM** implement a small interface and are selected via config. Defaults are cloud-light; local backends are optional extras.
+
+| | Default (light) | Local (extra `[local]`) | Premium cloud |
+|---|---|---|---|
+| TTS | `edge-tts` | `silero`, `piper` | `elevenlabs`, `openai-tts` |
+| STT | `openai-whisper-api` | `faster-whisper` | `deepgram` |
+| LLM | `anthropic` (Haiku 4.5) | `openai-compat` (Ollama / LM Studio) | `openai` |
+
+## Directory layout
+
+```
+src/voice_copilot/
+  core/        event bus, event types, config
+  adapters/    CLI adapters (claude_code, codex, proxy, pty_fallback)
+  llm/         commentator LLM providers
+  tts/         TTS providers
+  stt/         STT providers
+  commentator/ debounce + prompt assembly + i18n
+  dialog/      queue + quick-aside + interrupt flow
+  web/         FastAPI app + static popup/settings UI
+  hotkeys.py   global hotkey listener (pynput)
+  tray.py      system tray icon (pystray)
+  cli.py       `voice-copilot run <target-cli> -- ...`
+```
+
+## Run model
+
+`voice-copilot run claude -p "implement feature X"` does:
+
+1. Start FastAPI on `127.0.0.1:<port>`, open browser to popup URL.
+2. Spawn the tray icon and register global hotkey.
+3. Optionally start mitmproxy and set `ANTHROPIC_BASE_URL` for the child.
+4. Spawn the child CLI with appropriate JSON-stream flags.
+5. Pipe events into the bus → commentator → TTS.
+6. When user presses push-to-talk → record → STT → dialog manager decides: quick-aside / queue / manual.
+
+## Conventions
+
+- Python 3.11+. Formatter: **ruff format**. Linter: **ruff**. Type checker: **mypy** (strict on new code).
+- Package manager: **uv** (`uv sync`, `uv run voice-copilot ...`). pipx also supported.
+- Config lives at `~/.voice-copilot/config.yaml`; secrets in OS keyring or `.env`.
+- Prompt files are markdown in `src/voice_copilot/commentator/prompts/<lang>.md` — treat them as product surface.
+- No hidden retries, no silent fallbacks between providers: if configured provider fails, surface the error to the popup and stop narrating. Fail loud.
+
+## Non-goals (at least for v1)
+
+- We do **not** try to be a TUI replacement. The browser popup is the UI for voice-copilot itself; the underlying CLI's TUI (if any) stays as-is.
+- We do **not** re-implement CLIs. If Claude Code doesn't expose some event, we accept that and narrate what we have.
+- We do **not** train models.
+
+## Memory for future Claude sessions
+
+Persistent notes about this user and project live in
+`C:\Users\vladi\.claude\projects\f---VOICE-COPILOT\memory\` (indexed by `MEMORY.md`).
+Use them — don't re-derive the project's purpose from scratch each session.

voice_copilot-0.0.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,30 @@
+# Code of Conduct
+
+Voice Copilot follows the Contributor Covenant Code of Conduct.
+
+## Our Pledge
+
+We pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- using welcoming and inclusive language
+- being respectful of differing viewpoints and experiences
+- giving and gracefully accepting constructive feedback
+- focusing on what is best for the community
+- showing empathy toward other community members
+
+Examples of unacceptable behavior include:
+
+- harassment, insults, or personal attacks
+- public or private harassment
+- publishing others' private information without explicit permission
+- other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to info@conus.vision. Project maintainers are responsible for clarifying and enforcing standards of acceptable behavior and may remove, edit, or reject comments, commits, code, issues, and other contributions that are not aligned with this Code of Conduct.
+
+This Code of Conduct is adapted from the Contributor Covenant, version 2.1.

voice_copilot-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to Voice Copilot
+
+Thanks for helping make Voice Copilot better. The project is early, so small focused pull requests are especially valuable: bug fixes, provider improvements, tests, docs, and reports from real CLI workflows.
+
+## Development Setup
+
+Voice Copilot uses Python 3.11+ and `uv`.
+
+```bash
+git clone https://github.com/voice-copilot/voice-copilot.git
+cd voice-copilot
+uv sync --extra dev
+uv run voice-copilot serve --demo
+```
+
+Useful checks before opening a pull request:
+
+```bash
+uv run ruff format .
+uv run ruff check .
+uv run mypy src/voice_copilot
+uv run pytest
+```
+
+## Pull Requests
+
+- Keep changes focused on one problem or feature.
+- Add or update tests for behavioral changes.
+- Update README or docs when user-facing behavior changes.
+- Do not include API keys, tokens, local config files, or generated cache directories.
+- Prefer explicit errors over silent fallbacks. If a provider fails, surface the failure.
+
+## Tests
+
+Unit tests live under `tests/unit/`. Tests should avoid real network calls and external API providers unless they are explicitly marked as integration tests.
+
+## Code Style
+
+- Format with `ruff format`.
+- Lint with `ruff check`.
+- Keep new code compatible with strict `mypy`.
+- Use typed interfaces for providers and adapters.
+- Keep secrets in the OS keyring or environment variables, never in config files.
+
+## Reporting Issues
+
+Please include:
+
+- Operating system and Python version
+- Voice Copilot version or commit SHA
+- Target CLI and version, if relevant
+- Provider configuration, without secret values
+- Reproduction steps and expected behavior
+
+Security issues should be reported privately. See `SECURITY.md`.

voice_copilot-0.0.1/Dockerfile

@@ -0,0 +1,52 @@
+# Dockerfile for voice-copilot.
+#
+# CAVEATS — read before running:
+#   1. Microphone: the browser only grants `getUserMedia` on trusted origins.
+#      That means `localhost`. Running the server in a container and opening
+#      the popup from the host works ONLY if you use `--network host` (Linux)
+#      or terminate HTTPS in front of the container. On Docker Desktop for
+#      Mac/Windows, the host sees the server as `localhost:8765` via port
+#      forwarding — modern Chromium treats that as a secure context, so mic
+#      access usually works. Firefox is stricter.
+#   2. Target CLIs: `claude`, `codex`, etc. are NOT installed in this image.
+#      You'd typically mount your workspace and install them inside, or run
+#      only `voice-copilot serve` and talk to a CLI running on the host.
+#   3. Global hotkeys: `pynput` needs an X server / input device on Linux. In
+#      a headless container they silently no-op. Use the in-popup buttons.
+#   4. Tray icon: `pystray` is skipped when `--tray=false` is passed.
+#
+# In short: the container is most useful for `voice-copilot serve --demo` and
+# for the `proxy` mode; for full voice-paired coding, install on the host.
+
+FROM python:3.12-slim AS base
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential \
+        curl \
+        ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE ./
+COPY voice_copilot ./voice_copilot
+
+RUN pip install --upgrade pip && pip install .
+
+# Keyring needs a backend in the container. Fall back to a plaintext file
+# backend — keys still don't leave the container image because nothing is
+# baked in; operators mount /root/.local/share/python_keyring at runtime.
+RUN pip install keyrings.alt
+
+EXPOSE 8765 8766
+
+ENV VOICE_COPILOT_HOST=0.0.0.0 \
+    VOICE_COPILOT_PORT=8765
+
+# Default entrypoint — demo mode, no hotkeys, no tray.
+ENTRYPOINT ["voice-copilot"]
+CMD ["serve", "--host", "0.0.0.0", "--no-open", "--no-hotkeys", "--no-tray", "--demo"]

voice_copilot-0.0.1/LICENSE

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

voice_copilot-0.0.1/LICENSING.md

@@ -0,0 +1,20 @@
+# Licensing Notes
+
+Voice Copilot core is open-source under the MIT license.
+
+## What this means
+
+- You can use, modify, fork, redistribute, and commercialize this repository
+- You can build your own workflows, integrations, and products on top of it
+- Contributions and third-party adoption are intentionally low-friction
+
+## Branding
+
+The MIT license applies to the code in this repository. It does not grant
+trademark rights to the Voice Copilot or Conus Vision names, logos, or brand
+identity except for fair descriptive reference.
+
+## Contact
+
+- Email: info@conus.vision
+- Website: https://conus.vision