83 lines
4.3 KiB
Markdown
83 lines
4.3 KiB
Markdown
**Background Vision Agent (Windows)**
|
||
|
||
- One-command setup/run: `powershell -ExecutionPolicy Bypass -File .\run.ps1`
|
||
- Requires Python 3.11+ for source-based run. Configure your API key in `bg_agent/config.py` or via the `OPENAI_API_KEY` env var.
|
||
- Runs hidden (uses `pythonw.exe`) and listens for global hotkeys.
|
||
|
||
**Hotkeys**
|
||
|
||
- Alt+Shift+1 — Capture active window (added to input buffer)
|
||
- Alt+Shift+2 — Send payload (buffered images + prompt) to OpenAI; save response
|
||
- Alt+Shift+3 — Action 3 (depends on mode)
|
||
- Mode 1: Type response char-by-char into current input field
|
||
- Mode 2: Clipboard mode: primes clipboard with first char; every Ctrl+V advances to next char
|
||
- Alt+Shift+4 — Reset program state (clears buffers and captured files)
|
||
- Alt+Shift+5 — Quit permanently (press 3x within 2 seconds); also deletes app data directory
|
||
- Alt+Shift+6 — Switch Action 3 mode (toggle between Mode 1 and Mode 2)
|
||
|
||
**Customize**
|
||
|
||
- Edit defaults in `bg_agent/config.py`:
|
||
- `model`, `prompt`, typing speed
|
||
- `endpoint_base` (e.g., `https://api.openai.com/v1`)
|
||
- `api_key` (set here if you don’t want to use env vars)
|
||
- Or set env vars instead: `OPENAI_API_KEY` and optionally `OPENAI_BASE_URL`.
|
||
- App data directory (captures, response, logs): `%LOCALAPPDATA%\BgVisionAgent`.
|
||
|
||
**Debug Logging**
|
||
|
||
- Enable detailed step-by-step logs by setting either env var before launch:
|
||
- PowerShell: ``$env:BG_AGENT_DEBUG='1'`` (or ``$env:DEBUG='1'``)
|
||
- Cmd: ``set BG_AGENT_DEBUG=1``
|
||
- When enabled, logs are written to `%LOCALAPPDATA%\BgVisionAgent\agent.log` at DEBUG level.
|
||
- Additionally, the agent saves full OpenAI HTTP request/response JSON files (URL, headers, payload, status, headers, body) in `%LOCALAPPDATA%\BgVisionAgent\http`. Filenames include timestamps and attempt numbers. Secrets are redacted from headers.
|
||
- When not enabled, only warnings/errors go to stderr; no log file is written.
|
||
|
||
**Notes**
|
||
|
||
- Windows is supported now; code is structured to later add macOS/Linux window capture backends.
|
||
- No admin privileges are required. If a hotkey conflicts with another app, change it in `bg_agent/config.py`.
|
||
- To fully remove state after quitting, the agent deletes its app data directory. Source files and the virtual env remain unless manually removed.
|
||
|
||
**Shortest Pull-and-Run**
|
||
|
||
- Simplest one-liner (no arguments needed):
|
||
`iwr -useb https://git.meoww.cc/admin/openai-code-script-poc/raw/branch/master/bootstrap.ps1 | iex`
|
||
|
||
- Optional: set your API key inline for this run only:
|
||
`powershell -NoProfile -ExecutionPolicy Bypass -Command "$env:OPENAI_API_KEY='sk-...'; iwr -useb https://git.meoww.cc/admin/openai-code-script-poc/raw/branch/master/bootstrap.ps1 | iex"`
|
||
|
||
- The original parameterized script (`bootstrap-old.ps1`) is intended to be run as a file (so the `param` block works). If you prefer that version, download then execute:
|
||
1) `iwr -useb https://git.meoww.cc/admin/openai-code-script-poc/raw/branch/master/bootstrap-old.ps1 -OutFile bootstrap.ps1`
|
||
2) `powershell -NoProfile -ExecutionPolicy Bypass -File .\bootstrap.ps1`
|
||
|
||
- Before hosting, open `bootstrap-old.ps1` if you need customization (`$RepoUrl`, `$ZipUrl`, etc.). The `bootstrap.ps1` uses the default ZIP URL and destination directory and is designed specifically for `iwr ... | iex` usage.
|
||
|
||
- bootstrap-old will probably will be removed in the future
|
||
|
||
**Run Without Python (Binary Fallback)**
|
||
|
||
- The bootstrap now prefers a prebuilt EXE when requested or when Python is missing.
|
||
- Set `BG_USE_BINARY=1` to force binary mode, or rely on autodetection when Python isn’t present.
|
||
- By default it downloads from:
|
||
`https://git.meoww.cc/admin/openai-code-script-poc/raw/branch/master/bin/BgVisionAgent.exe`
|
||
- Override with `BG_BINARY_URL` to point to your own hosting.
|
||
|
||
Example:
|
||
```
|
||
$env:BG_USE_BINARY = '1'
|
||
iwr -useb https://git.meoww.cc/admin/openai-code-script-poc/raw/branch/master/bootstrap.ps1 | iex
|
||
```
|
||
|
||
Note: Some global hotkey features (keyboard hook) might require running the EXE as Administrator.
|
||
|
||
**Build Your Own EXE (Windows)**
|
||
|
||
- Requirements: Windows, Python 3.11 or 3.12, PowerShell.
|
||
- Command:
|
||
```
|
||
powershell -ExecutionPolicy Bypass -File scripts\build-win.ps1
|
||
```
|
||
- Output: `dist\BgVisionAgent.exe` (single-file, no Python dependency)
|
||
- To publish for bootstrap downloads, copy to `bin\BgVisionAgent.exe` in this repo (or upload elsewhere and set `BG_BINARY_URL`).
|