Alice-Shell

Hands-free terminal + GUI with offline STT (Vosk), Coqui TTS, and confirm-before-execute safety.

View on GitHub Features Blog Install Guide License

Key features

Voice prompt → run 
Alice prompt
> draft a git commit for staged files
Alice run
[MODEL] CMD: git commit -m "Refactor voice router; add v-exec guard"
[MODEL] EXPL: Create a commit with a clear message
Alice execute
✔ executed: git commit -m "Refactor voice router; add v-exec guard"

Edit prompts by voice or keyboard, send to the model, then explicitly confirm before anything runs.

“v-” controls 
v-guided-off
v-voice 3
v-speed 1.2
v-history
# shows the buffer slice that will be sent
v-exec

Toggle guided narration, pick voices, preview the context slice, and gate execution with v-exec.

Self-directed tests 
Alice test voice
Alice test shell
Alice test both
[TEST] voice: ok · shell: ok
[TEST] logs written to ./logs/

Built-in checks exercise voice handlers and shell suggesters without running OS commands.

Voice flows

Alice prompt         # start dictating a prompt
Alice run            # send current prompt to the model
Alice repeat         # speak the current prompt
Alice execute        # execute last suggested CMD (after confirm)
Alice test voice     # exercise voice handlers
Alice test shell     # exercise shell suggester
Alice test both      # run both test suites

v- controls

v-help               # show help
v-exec               # confirm/execute pending command
v-guided-on/off      # toggle narration
v-clear              # clear buffer
v-buffer session     # set buffer mode (session/anchor/last)
v-history            # show the slice that will be sent
v-voice 2            # pick TTS voice
v-speed 1.2          # set TTS speed

alice-shell.py · Voice Shell

  • Offline STT (Vosk) + Coqui TTS.
  • Confirm-before-exec: nothing runs without v-exec or “Alice execute”.
  • Shell passthrough: type normal commands; Alice observes and logs.
  • Smart routing: route between shell and internal v-* ops.
  • Prompt editing: “Alice prompt” → “Alice run” → “Alice repeat”.
  • Buffer modes: session, anchor, last; inspect with v-history.
  • Guided narration: v-guided-on/off.
  • Self-directed tests: Alice test voice / shell / both.

alice.py · Calibration GUI

  • Mic calibration; verify STT & TTS quickly.
  • Model & reasoning pickers; optional “Speak response”.
  • Shares config with the shell for consistent behavior.
  • Great for voice drift checks and environment resets.

Safety

  • Commands are suggested first, then explicitly confirmed.
  • Transparent logs so you can audit what was proposed and run.

Blog / devlog

No DEVLOG/BLOG/CHANGELOG found in the repo yet.

Installation

$ git clone https://github.com/gndev1/alice-shell.git
$ cd alice-shell
$ python3 -m venv .venv && source .venv/bin/activate
$ pip install -r requirements.txt
# Start the voice shell:
$ python3 alice-shell.py
# Or open the calibration GUI:
$ python3 alice.py

See the repository for platform notes, Vosk STT model setup, and Coqui TTS tips.

Guide

Open the full manual

Manual: Alice‑Shell

1) Overview

Alice‑Shell is a voice‑enabled assistant for your terminal with a companion calibration GUI. It listens via offline Vosk STT, speaks via Coqui TTS, and never runs OS commands until you explicitly confirm (e.g., with v-exec or by saying “Alice execute”).

2) Install

$ git clone https://github.com/gndev1/alice-shell.git
$ cd alice-shell
$ python3 -m venv .venv && source .venv/bin/activate
$ pip install -r requirements.txt

3) Launch

  • Voice shell: python3 alice-shell.py
  • Calibration GUI: python3 alice.py

4) Voice flow

Alice prompt         # start dictating a prompt
Alice run            # send the current prompt to the model
Alice repeat         # speak the current prompt
Alice execute        # execute last suggested command (after explicit confirm)

5) v- controls

v-help               # show help
v-exec               # confirm/execute the pending command
v-guided-on/off      # toggle spoken guidance
v-clear              # clear buffer
v-buffer session     # buffer mode: session | anchor | last
v-history            # show the slice that will be sent
v-voice 2            # choose TTS voice (index)
v-speed 1.2          # TTS speed

6) Testing (self‑directed)

Alice test voice
Alice test shell
Alice test both

These routines validate voice handlers and shell suggesters without executing OS commands. Logs go to ./logs/.

7) Buffering and history

Use v-buffer to choose how much context is sent to the model (session, anchor, last). Inspect what will be sent with v-history.

8) Safety & confirmation

  • All suggested commands are read back before execution.
  • Nothing runs unless you explicitly confirm via v-exec or “Alice execute”.

9) Troubleshooting

  • Mic not detected: verify OS input device, then re‑run the calibration GUI.
  • STT too noisy: try a closer mic, reduce input gain, or switch to a smaller Vosk model.
  • TTS too fast/slow: adjust with v-speed; pick a different voice with v-voice.

10) Notes

  • All sensitive actions are behind explicit confirmation.
  • Designed for hands‑free workflows; keyboard still fully supported.

License & notices

From README.md

License

This project is licensed under the **MIT License** with explicit liability exclusion.

See the full text in [LICENSE](LICENSE).

LICENSE

MIT License

Copyright (c) 2025 Gregory Norman

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:

1. The above copyright notice and this permission notice shall be included in
   all copies or substantial portions of the Software.

2. 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.

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.

Disclaimers & safety

Alice-Shell suggests commands and reads them back, but only runs what you explicitly confirm (e.g., with “v-exec”).