Local Voice Agent

A voice-controlled agent that runs on your PC: local speech-to-text, a local LLM as the brain (no API server — the model loads directly into the Python process), and tools to run shell commands, install/open/close apps, control the mouse/keyboard, drive a real browser, read/send email, and post content to social platforms. Full autonomy — it acts without asking for confirmation, and logs every action to agent.log.

main.py            <- entry point, the voice loop
config.yaml         <- model path, autonomy setting, email + social credentials
requirements.txt
agent/
  __init__.py
  brain.py           <- loads the model, runs the tool-calling loop
  tools.py            <- shell, apps, GUI, browser, social, email, files
  social.py            <- platform clients (Twitter/X, YouTube, Meta, TikTok)
  scheduler.py          <- lets any tool be scheduled for a future time
  voice_in.py            <- local speech-to-text (push-to-talk or toggle mode)
  voice_out.py            <- local text-to-speech (voice/rate/volume, graceful fallback)
  tiktok_oauth.py          <- one-time local OAuth handshake for TikTok

1. Install prerequisites

Python 3.10+ — https://www.python.org/downloads/ (check "Add to PATH")

Build tools for llama-cpp-python — pip install llama-cpp-python usually grabs a prebuilt Windows wheel. If pip tries to compile from source and fails, install the free "Desktop development with C++" workload from https://visualstudio.microsoft.com/visual-cpp-build-tools/ and retry.

2. Install Python dependencies

pip install -r requirements.txt
playwright install chromium

faster-whisper downloads a small speech model (~150MB) on first run; playwright install chromium downloads a local Chromium browser (~150MB). Both are one-time downloads, not remote APIs.

3. Download a local model file

Llama 3.2 3B Instruct, Q4_K_M (~2GB, fast on CPU) — good fit for your AMD 4GB VRAM / 32GB RAM setup: https://huggingface.co/bartowski/Llama-3.2-3B-Instruct-GGUF/blob/main/Llama-3.2-3B-Instruct-Q4_K_M.gguf

Create a models folder next to main.py and put the file there: local-agent/models/Llama-3.2-3B-Instruct-Q4_K_M.gguf. For stronger reasoning at the cost of speed, look for a Q4_K_M GGUF of Qwen2.5-7B-Instruct or Llama-3.1-8B-Instruct from the same uploader (bartowski) and repoint model.path.

4. (Optional) Enable email

Fill in the email section of config.yaml. For Gmail: turn on 2-Step Verification, generate an app password at https://myaccount.google.com/apppasswords, and set enabled: true.

5. (Optional) Connect social platforms

Each platform is its own gate, and they're genuinely not equal in effort. Read this before you start:

X / Twitter

1. Go to https://developer.x.com, create a Project + App.
2. As of 2026 this requires a paid plan for write access for new developer accounts — check current pricing on their site before committing, it changes.
3. In the app's "Keys and tokens" tab, generate an API Key/Secret and an Access Token/Secret with Read+Write permission.
4. Paste all four into config.yaml under social.twitter, set enabled: true.

YouTube

1. Go to https://console.cloud.google.com, create a project.
2. Enable "YouTube Data API v3" (APIs & Services → Library).
3. Create an OAuth Client ID (APIs & Services → Credentials → Create Credentials → OAuth client ID → Desktop app). Download the JSON.
4. Save it next to main.py, point social.youtube.client_secret_path at it, set enabled: true.
5. First time you use post_youtube, a browser window opens for you to grant access once; after that it's cached in youtube_token.json.
6. Uploading costs quota — the exact per-upload cost has changed recently and sources disagree on the current number, so check the quota calculator in Google Cloud Console for today's figure rather than trusting a fixed number here.

...