free-code

Vision Mode — See the screen. Hear your voice. Respond naturally.

What is Vision Mode?

Multimodal AI agent with eyes, ears, and voice — hands-free assistance powered by your screen and speech.

Vision Mode brings multimodal capabilities to free-code: screen capture, speech-to-text (STT), and text-to-speech (TTS). The agent can see what's on your screen, listen to your voice, and speak answers back.

Built on a snapshot-at-question-time model — no continuous video upload, no streaming. The agent receives one image at the moment you ask, plus the conversation history. This keeps cost low, latency reasonable, and privacy high.

Example
Open a browser with an error page, say "free-code, what is this error?", and the agent captures the screen, reads the stack trace, and answers out loud — zero typing required.

How it works

Three interaction modes, one seamless pipeline.

Three commands

Mode	Command	Use case
On-demand vision	`/see <question>`	Capture screen once, ask about it. Typed question, instant screenshot.
Push-to-talk	`/voice [context]`	Record audio, transcribe, send. No screen capture unless explicitly requested.
Live hands-free	`/vision live on`	Continuous listening with wake word. Auto-captures when vision keywords detected. Speaks responses.

The pipeline

Step	What happens	Configurable backends
1. Screen capture	Grabs a single frame of the current screen	Portal (Wayland), scrot, gnome-screenshot, spectacle, import, screencapture (macOS), PowerShell
2. Image resize	Downscales to max 1568px (configurable) with Photon WASM	JPEG quality 85 (default), ~1.1–1.6k tokens per image
3. Audio record	Records microphone input until stopped (PTT or VAD)	pw-record, arecord, sox, ffmpeg
4. Speech-to-text	Transcribes audio to text	OpenAI Whisper, Groq Whisper, local whisper.cpp
5. Agent turn	Sends text + optional image to the model	Any vision-capable model: GPT-4o, Claude 3.5, Gemini 2.0 Flash, etc.
6. Text-to-speech	Speaks the assistant's reply (live mode only)	OpenAI TTS, espeak, macOS say

Why snapshot instead of video?
A 10-second video at 1 frame per second = 10 images = 10–15k tokens. One snapshot at question time = 1.5k tokens. The agent doesn't need to see continuous motion — it needs context for the question you asked.

Flow diagrams

Visualizing the three interaction modes.

1 · On-demand vision (`/see`)

Single-shot: question → capture → resize → model answer

2 · Push-to-talk (`/voice`)

Push-to-talk: record → transcribe → send (or place in editor for review)

3 · Live hands-free mode (`/vision live on`)

Live loop: listen → transcribe → check keywords → capture (if needed) → model → speak → repeat

Commands

All vision-mode slash commands and shortcuts.

Command	Description
`/see <question>`	Capture screen and ask about it (one-shot vision)
`/voice [context]`	Push-to-talk: record, transcribe, send (or review)
`/vision live on`	Start continuous hands-free mode with wake word
`/vision live off`	Stop live mode
`/vision status`	Show current backends, language, mode settings
`/vision backends`	List available capture/STT/TTS backends and whether they're installed
`/vision config`	View all configuration values
`/vision config <key>`	View a single config value
`/vision config <key> <value>`	Set a config value

Keyboard shortcut

Push-to-talk is registered as a global shortcut (default: configurable via VISION_SHORTCUT env var or vision.json). Press once to start recording, press again to stop and transcribe.

In live mode
The PTT shortcut interrupts the current capture/recording — useful if the agent is listening too long or you want to barge in mid-turn.

Configuration

All settings, environment variables, and config file location.

Config file

Vision Mode settings are stored in ~/.free-code/vision.json. Edit directly or use /vision config <key> <value>.

Environment variables (override config file)

Variable	Description
`VISION_CAPTURE_BACKEND`	Capture method: `auto`, `portal`, `grim`, `scrot`, `import`, `screencapture`, `powershell`
`VISION_STT_BACKEND`	STT backend: `auto`, `openai`, `groq`, `whisper-cpp`
`VISION_TTS_BACKEND`	TTS backend: `auto`, `openai`, `espeak`, `say`
`VISION_LANGUAGE`	Language code: `es`, `en`, `auto`
`VISION_VOICE_MODE`	Transcript destination: `send` (automatic) or `review` (placed in editor)
`VISION_SHORTCUT`	PTT hotkey (e.g., `ctrl+shift+space`)
`OPENAI_API_KEY`	Required for OpenAI STT/TTS
`GROQ_API_KEY`	Required for Groq STT

CLI flags (override env vars)

Flag	Description
`--vision-capture-backend <id>`	Force a specific capture backend
`--vision-stt-backend <id>`	Force a specific STT backend
`--vision-tts-backend <id>`	Force a specific TTS backend
`--vision-language <code>`	Override language
`--vision-voice-mode <mode>`	Override voice mode

All config keys

Key	Default	Description
`captureBackend`	`"auto"`	Screen capture method
`captureInteractive`	`true`	Allow monitor/window selection dialogs
`captureMaxWidth`	`1568`	Max image dimension before resize (0 = no resize)
`captureJpegQuality`	`85`	JPEG compression quality (0–100)
`sttBackend`	`"auto"`	Speech-to-text backend
`sttModel`	`"whisper-1"`	Model name for API STT (OpenAI/Groq)
`ttsBackend`	`"auto"`	Text-to-speech backend
`ttsModel`	`"tts-1"`	TTS model (OpenAI)
`ttsVoice`	`"alloy"`	TTS voice (OpenAI: alloy, echo, fable, onyx, nova, shimmer)
`language`	`"auto"`	STT language code
`voiceMode`	`"review"`	Where transcript goes: `send` or `review`
`shortcut`	`null`	PTT hotkey (e.g., `"ctrl+shift+space"`)
`voiceCommandDuration`	`6000`	Max recording duration for `/voice` command (ms)
`liveTurnMaxMs`	`8000`	Max recording duration per live-mode turn (ms)
`liveAlwaysCapture`	`false`	Capture screen on every utterance (ignore keyword detection)
`liveWakeWord`	`"freecode"`	Wake word to activate processing (comma-separated for multiple)
`liveSpeak`	`true`	Speak assistant responses in live mode
`liveIndicator`	`true`	Show status indicator when live mode is active

Example: Spanish setup with Groq STT

export GROQ_API_KEY="gsk_..."
/vision config language es
/vision config sttBackend groq
/vision config liveWakeWord "oye,free-code"
/vision live on

Privacy & cost

What gets captured, when, and how much it costs.

Privacy model

Explicit opt-in: Vision Mode commands must be invoked manually. Live mode requires /vision live on.
No continuous upload: Screen is captured only at the moment you ask a question (or when vision keywords are detected in live mode).
Visible indicator: Live mode shows a status indicator (👁 live · listening…) so you know it's active.
Portal consent (Wayland): The XDG Desktop Portal shows a permission dialog before granting screen access — OS-level consent.
Local backends: Use whisper.cpp (local STT) + espeak/say (local TTS) for fully private, zero-API mode.

Token cost

One downscaled image (1568px max, JPEG quality 85) ≈ 1.1–1.6k input tokens.

Scenario	Images sent	Est. image tokens
10 `/see` questions	10	~11–16k
30-question live session (vision keywords in half)	15	~16–24k
100-question live session (liveAlwaysCapture=true)	100	~110–160k

Compare to text-only: a 500-line file ≈ 3–5k tokens. Vision adds cost, but the snapshot model keeps it reasonable — you're not streaming 30fps video.

Latency budget

Target: under 5 seconds from "stop talking" to "agent starts speaking" (live mode).

VAD silence detection: ~300ms
Local whisper.cpp (base model): ~500–1000ms
Screen capture: ~100ms
Model first token: ~1–2s (depends on provider/load)
TTS first audio chunk: ~500ms (streaming)

Total: ~2.4–4s under ideal conditions. Groq STT can shave off another ~500ms (faster than local Whisper).

Installation & dependencies

What to install for each backend.

Vision Mode is included in the default free-code installation. You need to install system dependencies for the backends you want to use.

Screen capture

Pick one (or install multiple; auto will choose the best available):

Linux/Wayland: xdg-desktop-portal-gnome (recommended), or grim / gnome-screenshot / spectacle / scrot / ImageMagick import
Linux/X11: scrot or import
macOS: screencapture (built-in, no install needed)

# Ubuntu/Debian (Wayland)
sudo apt install xdg-desktop-portal-gnome

# Fedora (Wayland)
sudo dnf install xdg-desktop-portal-gnome

# Arch (Wayland)
sudo pacman -S xdg-desktop-portal-gnome

# Fallback: scrot (X11)
sudo apt install scrot

Audio recording

One of:

pw-record (PipeWire, modern Linux — usually pre-installed on recent distros)
arecord (ALSA)
sox (cross-platform)
ffmpeg

# Check if pw-record exists (PipeWire)
which pw-record

# Install ALSA utils (includes arecord)
sudo apt install alsa-utils

# Or install SoX
sudo apt install sox

Speech-to-text

API-based (easiest):

# OpenAI Whisper
export OPENAI_API_KEY="sk-..."

# Groq (faster, free tier available)
export GROQ_API_KEY="gsk_..."

Local (no API cost, fully private):

Install whisper.cpp:

git clone https://github.com/ggerganov/whisper.cpp.git
cd whisper.cpp
make
# Download a model (base is fast, small is smaller, large is most accurate)
bash ./models/download-ggml-model.sh base
# Ensure 'whisper' binary is in PATH or specify path via VISION_WHISPER_CPP_PATH

Text-to-speech

API-based:

export OPENAI_API_KEY="sk-..."   # for tts-1 model

Local:

# Linux: espeak
sudo apt install espeak

# macOS: say (built-in, no install needed)

Verify backends

After installing dependencies, check what's available:

/vision backends

Output shows ✓ for available backends, ✗ for missing ones.

Examples

Common workflows and use cases.

1. Debug a visual error

Open a browser with a stack trace or error page:

/see what is this error and how do I fix it?

Agent captures the screen, reads the stack trace, and explains the issue.

2. Code review via screen share

Open a diff or PR in GitHub/GitLab:

/see review this diff for potential issues

3. Hands-free pair programming

Start live mode while coding:

/vision config liveWakeWord "free-code"
/vision config language en
/vision live on

# Now say: "free-code, what does this function do?"
# Agent captures screen, sees the code, answers out loud.

4. Transcribe meeting notes

Use push-to-talk to record summaries without typing:

/voice
# Press PTT hotkey, speak notes, release
# Transcript appears in editor for review before sending

5. Fully private local mode

No API calls, all processing on your machine:

/vision config sttBackend whisper-cpp
/vision config ttsBackend espeak   # or 'say' on macOS
/vision config captureBackend portal  # or 'scrot' on X11

# Now all /see, /voice, and live mode use local backends only

Troubleshooting

Common issues and fixes.

"No capture backend available"

Install at least one screen capture tool. Check what's available:

/vision backends

On Wayland, install xdg-desktop-portal-gnome. On X11, install scrot.

"No audio recorder found"

Install one of: pw-record, arecord, sox, or ffmpeg.

which pw-record arecord sox ffmpeg

"Could not resize the screenshot (Photon unavailable)"

The Photon WASM asset is missing. Reinstall free-code or check packages/coding-agent/assets/photon_rs_bg.wasm.

Live mode doesn't activate on speech

Check wake word configuration:

/vision config liveWakeWord

Make sure you say the exact wake word at the start of your utterance. Try:

/vision config liveWakeWord "hey,oye,freecode"

This allows any of those three to activate.

Images are too large / too expensive

Reduce max dimension or JPEG quality:

/vision config captureMaxWidth 1200
/vision config captureJpegQuality 75

STT transcribes incorrectly

Set the correct language explicitly:

/vision config language es   # for Spanish
/vision config language en   # for English

TTS speaks too slowly / wrong voice

Change voice (OpenAI TTS):

/vision config ttsVoice nova   # or alloy, echo, fable, onyx, shimmer

free-code

Modo Visión — Ve la pantalla. Escucha tu voz. Responde con naturalidad.

¿Qué es el Modo Visión?

Agente de IA multimodal con ojos, oídos y voz — asistencia manos libres impulsada por tu pantalla y tu voz.

El Modo Visión aporta capacidades multimodales a free-code: captura de pantalla, voz a texto (STT) y texto a voz (TTS). El agente puede ver lo que hay en tu pantalla, escuchar tu voz y responder en voz alta.

Construido sobre un modelo de captura en el momento de la pregunta — sin subida continua de video, sin streaming. El agente recibe una imagen en el momento en que preguntas, junto con el historial de la conversación. Esto mantiene el costo bajo, la latencia razonable y la privacidad alta.

Ejemplo
Abre un navegador con una página de error, di "free-code, ¿qué es este error?", y el agente captura la pantalla, lee el stack trace y responde en voz alta — sin necesidad de escribir nada.

Cómo funciona

Tres modos de interacción, un solo flujo continuo.

Tres comandos

Modo	Comando	Caso de uso
Visión bajo demanda	`/see <question>`	Captura la pantalla una vez y pregunta sobre ella. Pregunta escrita, captura instantánea.
Pulsar para hablar	`/voice [context]`	Graba audio, transcribe, envía. Sin captura de pantalla salvo que se solicite explícitamente.
Manos libres en vivo	`/vision live on`	Escucha continua con palabra de activación. Captura automáticamente cuando se detectan palabras clave de visión. Habla las respuestas.

El flujo

Paso	Qué sucede	Backends configurables
1. Captura de pantalla	Toma un único fotograma de la pantalla actual	Portal (Wayland), scrot, gnome-screenshot, spectacle, import, screencapture (macOS), PowerShell
2. Redimensionado de imagen	Reduce la escala a un máximo de 1568px (configurable) con Photon WASM	Calidad JPEG 85 (por defecto), ~1.1–1.6k tokens por imagen
3. Grabación de audio	Graba la entrada del micrófono hasta que se detiene (PTT o VAD)	pw-record, arecord, sox, ffmpeg
4. Voz a texto	Transcribe el audio a texto	OpenAI Whisper, Groq Whisper, whisper.cpp local
5. Turno del agente	Envía texto + imagen opcional al modelo	Cualquier modelo con capacidad de visión: GPT-4o, Claude 3.5, Gemini 2.0 Flash, etc.
6. Texto a voz	Habla la respuesta del asistente (solo en modo en vivo)	OpenAI TTS, espeak, macOS say

¿Por qué captura en lugar de video?
Un video de 10 segundos a 1 fotograma por segundo = 10 imágenes = 10–15k tokens. Una sola captura en el momento de la pregunta = 1.5k tokens. El agente no necesita ver movimiento continuo — necesita contexto para la pregunta que hiciste.

Diagramas de flujo

Visualizando los tres modos de interacción.

1 · Visión bajo demanda (`/see`)

Un solo disparo: pregunta → captura → redimensionado → respuesta del modelo

2 · Pulsar para hablar (`/voice`)

Pulsar para hablar: grabar → transcribir → enviar (o colocar en el editor para revisión)

3 · Modo manos libres en vivo (`/vision live on`)

Bucle en vivo: escuchar → transcribir → verificar palabras clave → capturar (si es necesario) → modelo → hablar → repetir

Comandos

Todos los comandos slash y atajos del modo visión.

Comando	Descripción
`/see <question>`	Captura la pantalla y pregunta sobre ella (visión de un solo disparo)
`/voice [context]`	Pulsar para hablar: graba, transcribe, envía (o revisa)
`/vision live on`	Inicia el modo manos libres continuo con palabra de activación
`/vision live off`	Detiene el modo en vivo
`/vision status`	Muestra los backends actuales, el idioma y la configuración del modo
`/vision backends`	Lista los backends de captura/STT/TTS disponibles e indica si están instalados
`/vision config`	Muestra todos los valores de configuración
`/vision config <key>`	Muestra un único valor de configuración
`/vision config <key> <value>`	Establece un valor de configuración

Atajo de teclado

Pulsar para hablar está registrado como un atajo global (por defecto: configurable mediante la variable de entorno VISION_SHORTCUT o vision.json). Presiona una vez para empezar a grabar, presiona de nuevo para detener y transcribir.

En modo en vivo
El atajo PTT interrumpe la captura/grabación actual — útil si el agente está escuchando demasiado tiempo o si quieres interrumpir en medio de un turno.

Configuración

Todos los ajustes, variables de entorno y ubicación del archivo de configuración.

Archivo de configuración

Los ajustes del Modo Visión se guardan en ~/.free-code/vision.json. Edítalo directamente o usa /vision config <key> <value>.

Variables de entorno (anulan el archivo de configuración)

Variable	Descripción
`VISION_CAPTURE_BACKEND`	Método de captura: `auto`, `portal`, `grim`, `scrot`, `import`, `screencapture`, `powershell`
`VISION_STT_BACKEND`	Backend STT: `auto`, `openai`, `groq`, `whisper-cpp`
`VISION_TTS_BACKEND`	Backend TTS: `auto`, `openai`, `espeak`, `say`
`VISION_LANGUAGE`	Código de idioma: `es`, `en`, `auto`
`VISION_VOICE_MODE`	Destino de la transcripción: `send` (automático) o `review` (colocado en el editor)
`VISION_SHORTCUT`	Tecla rápida PTT (p. ej., `ctrl+shift+space`)
`OPENAI_API_KEY`	Requerida para STT/TTS de OpenAI
`GROQ_API_KEY`	Requerida para STT de Groq

Opciones de la CLI (anulan las variables de entorno)

Opción	Descripción
`--vision-capture-backend <id>`	Fuerza un backend de captura específico
`--vision-stt-backend <id>`	Fuerza un backend STT específico
`--vision-tts-backend <id>`	Fuerza un backend TTS específico
`--vision-language <code>`	Anula el idioma
`--vision-voice-mode <mode>`	Anula el modo de voz

Todas las claves de configuración

Clave	Por defecto	Descripción
`captureBackend`	`"auto"`	Método de captura de pantalla
`captureInteractive`	`true`	Permite diálogos de selección de monitor/ventana
`captureMaxWidth`	`1568`	Dimensión máxima de la imagen antes de redimensionar (0 = sin redimensionar)
`captureJpegQuality`	`85`	Calidad de compresión JPEG (0–100)
`sttBackend`	`"auto"`	Backend de voz a texto
`sttModel`	`"whisper-1"`	Nombre del modelo para STT vía API (OpenAI/Groq)
`ttsBackend`	`"auto"`	Backend de texto a voz
`ttsModel`	`"tts-1"`	Modelo TTS (OpenAI)
`ttsVoice`	`"alloy"`	Voz TTS (OpenAI: alloy, echo, fable, onyx, nova, shimmer)
`language`	`"auto"`	Código de idioma para STT
`voiceMode`	`"review"`	Dónde va la transcripción: `send` o `review`
`shortcut`	`null`	Tecla rápida PTT (p. ej., `"ctrl+shift+space"`)
`voiceCommandDuration`	`6000`	Duración máxima de grabación para el comando `/voice` (ms)
`liveTurnMaxMs`	`8000`	Duración máxima de grabación por turno en modo en vivo (ms)
`liveAlwaysCapture`	`false`	Captura la pantalla en cada frase (ignora la detección de palabras clave)
`liveWakeWord`	`"freecode"`	Palabra de activación para procesar (separadas por comas para varias)
`liveSpeak`	`true`	Habla las respuestas del asistente en modo en vivo
`liveIndicator`	`true`	Muestra el indicador de estado cuando el modo en vivo está activo

Ejemplo: configuración en español con STT de Groq

export GROQ_API_KEY="gsk_..."
/vision config language es
/vision config sttBackend groq
/vision config liveWakeWord "oye,free-code"
/vision live on

Privacidad y costo

Qué se captura, cuándo y cuánto cuesta.

Modelo de privacidad

Opt-in explícito: los comandos del Modo Visión deben invocarse manualmente. El modo en vivo requiere /vision live on.
Sin subida continua: la pantalla se captura únicamente en el momento en que haces una pregunta (o cuando se detectan palabras clave de visión en modo en vivo).
Indicador visible: el modo en vivo muestra un indicador de estado (👁 live · listening…) para que sepas que está activo.
Consentimiento del portal (Wayland): el XDG Desktop Portal muestra un diálogo de permiso antes de conceder acceso a la pantalla — consentimiento a nivel del sistema operativo.
Backends locales: usa whisper.cpp (STT local) + espeak/say (TTS local) para un modo totalmente privado, sin API.

Costo en tokens

Una imagen reducida (máximo 1568px, calidad JPEG 85) ≈ 1.1–1.6k tokens de entrada.

Escenario	Imágenes enviadas	Tokens de imagen estimados
10 preguntas con `/see`	10	~11–16k
Sesión en vivo de 30 preguntas (palabras clave de visión en la mitad)	15	~16–24k
Sesión en vivo de 100 preguntas (liveAlwaysCapture=true)	100	~110–160k

En comparación con solo texto: un archivo de 500 líneas ≈ 3–5k tokens. La visión añade costo, pero el modelo de captura lo mantiene razonable — no estás transmitiendo video a 30fps.

Presupuesto de latencia

Objetivo: menos de 5 segundos desde que "dejas de hablar" hasta que "el agente empieza a hablar" (modo en vivo).

Detección de silencio VAD: ~300ms
whisper.cpp local (modelo base): ~500–1000ms
Captura de pantalla: ~100ms
Primer token del modelo: ~1–2s (depende del proveedor/carga)
Primer fragmento de audio TTS: ~500ms (streaming)

Total: ~2.4–4s en condiciones ideales. El STT de Groq puede recortar otros ~500ms (más rápido que Whisper local).

Instalación y dependencias

Qué instalar para cada backend.

El Modo Visión está incluido en la instalación por defecto de free-code. Necesitas instalar las dependencias del sistema para los backends que quieras usar.

Captura de pantalla

Elige una (o instala varias; auto elegirá la mejor disponible):

Linux/Wayland: xdg-desktop-portal-gnome (recomendado), o grim / gnome-screenshot / spectacle / scrot / ImageMagick import
Linux/X11: scrot o import
macOS: screencapture (incorporado, no requiere instalación)

# Ubuntu/Debian (Wayland)
sudo apt install xdg-desktop-portal-gnome

# Fedora (Wayland)
sudo dnf install xdg-desktop-portal-gnome

# Arch (Wayland)
sudo pacman -S xdg-desktop-portal-gnome

# Alternativa: scrot (X11)
sudo apt install scrot

Grabación de audio

Uno de estos:

pw-record (PipeWire, Linux moderno — normalmente preinstalado en distribuciones recientes)
arecord (ALSA)
sox (multiplataforma)
ffmpeg

# Verifica si pw-record existe (PipeWire)
which pw-record

# Instala las utilidades de ALSA (incluye arecord)
sudo apt install alsa-utils

# O instala SoX
sudo apt install sox

Voz a texto

Basado en API (lo más sencillo):

# OpenAI Whisper
export OPENAI_API_KEY="sk-..."

# Groq (más rápido, nivel gratuito disponible)
export GROQ_API_KEY="gsk_..."

Local (sin costo de API, totalmente privado):

Instala whisper.cpp:

git clone https://github.com/ggerganov/whisper.cpp.git
cd whisper.cpp
make
# Descarga un modelo (base es rápido, small es más pequeño, large es el más preciso)
bash ./models/download-ggml-model.sh base
# Asegúrate de que el binario 'whisper' esté en el PATH o especifica la ruta mediante VISION_WHISPER_CPP_PATH

Texto a voz

Basado en API:

export OPENAI_API_KEY="sk-..."   # para el modelo tts-1

Local:

# Linux: espeak
sudo apt install espeak

# macOS: say (incorporado, no requiere instalación)

Verificar backends

Después de instalar las dependencias, revisa qué está disponible:

/vision backends

La salida muestra ✓ para los backends disponibles, ✗ para los que faltan.

Ejemplos

Flujos de trabajo y casos de uso comunes.

1. Depurar un error visual

Abre un navegador con un stack trace o una página de error:

/see what is this error and how do I fix it?

El agente captura la pantalla, lee el stack trace y explica el problema.

2. Revisión de código mediante pantalla compartida

Abre un diff o PR en GitHub/GitLab:

/see review this diff for potential issues

3. Programación en pareja manos libres

Inicia el modo en vivo mientras programas:

/vision config liveWakeWord "free-code"
/vision config language en
/vision live on

# Ahora di: "free-code, ¿qué hace esta función?"
# El agente captura la pantalla, ve el código y responde en voz alta.

4. Transcribir notas de una reunión

Usa pulsar para hablar para grabar resúmenes sin escribir:

/voice
# Presiona la tecla rápida PTT, di las notas, suelta
# La transcripción aparece en el editor para revisión antes de enviarla

5. Modo local totalmente privado

Sin llamadas a la API, todo el procesamiento en tu máquina:

/vision config sttBackend whisper-cpp
/vision config ttsBackend espeak   # o 'say' en macOS
/vision config captureBackend portal  # o 'scrot' en X11

# Ahora todos los /see, /voice y el modo en vivo usan solo backends locales

Solución de problemas

Problemas comunes y sus soluciones.

"No hay backend de captura disponible"

Instala al menos una herramienta de captura de pantalla. Revisa qué está disponible:

/vision backends

En Wayland, instala xdg-desktop-portal-gnome. En X11, instala scrot.

"No se encontró grabador de audio"

Instala uno de: pw-record, arecord, sox, o ffmpeg.

which pw-record arecord sox ffmpeg

"No se pudo redimensionar la captura (Photon no disponible)"

Falta el recurso Photon WASM. Reinstala free-code o verifica packages/coding-agent/assets/photon_rs_bg.wasm.

El modo en vivo no se activa con la voz

Revisa la configuración de la palabra de activación:

/vision config liveWakeWord

Asegúrate de decir la palabra de activación exacta al comienzo de tu frase. Prueba:

/vision config liveWakeWord "hey,oye,freecode"

Esto permite que cualquiera de esas tres active el modo.

Las imágenes son demasiado grandes / demasiado costosas

Reduce la dimensión máxima o la calidad JPEG:

/vision config captureMaxWidth 1200
/vision config captureJpegQuality 75

El STT transcribe incorrectamente

Establece el idioma correcto de forma explícita:

/vision config language es   # para español
/vision config language en   # para inglés

El TTS habla demasiado lento / con la voz equivocada

Cambia la voz (TTS de OpenAI):

/vision config ttsVoice nova   # o alloy, echo, fable, onyx, shimmer

What is Vision Mode?

How it works

Three commands

The pipeline

Flow diagrams

1 · On-demand vision (/see)

2 · Push-to-talk (/voice)

3 · Live hands-free mode (/vision live on)

Commands

Keyboard shortcut

Configuration

Config file

Environment variables (override config file)

CLI flags (override env vars)

All config keys

Privacy & cost

Privacy model

Token cost

Latency budget

Installation & dependencies

Screen capture

Audio recording

Speech-to-text

Text-to-speech

Verify backends

Examples

1. Debug a visual error

2. Code review via screen share

3. Hands-free pair programming

4. Transcribe meeting notes

5. Fully private local mode

Troubleshooting

"No capture backend available"

"No audio recorder found"

"Could not resize the screenshot (Photon unavailable)"

Live mode doesn't activate on speech

Images are too large / too expensive

STT transcribes incorrectly

TTS speaks too slowly / wrong voice

¿Qué es el Modo Visión?

Cómo funciona

Tres comandos

El flujo

Diagramas de flujo

1 · Visión bajo demanda (/see)

2 · Pulsar para hablar (/voice)

3 · Modo manos libres en vivo (/vision live on)

Comandos

Atajo de teclado

Configuración

Archivo de configuración

Variables de entorno (anulan el archivo de configuración)

Opciones de la CLI (anulan las variables de entorno)

Todas las claves de configuración

Privacidad y costo

Modelo de privacidad

Costo en tokens

Presupuesto de latencia

Instalación y dependencias

Captura de pantalla

Grabación de audio

Voz a texto

Texto a voz

Verificar backends

Ejemplos

1. Depurar un error visual

2. Revisión de código mediante pantalla compartida

3. Programación en pareja manos libres

4. Transcribir notas de una reunión

5. Modo local totalmente privado

Solución de problemas

"No hay backend de captura disponible"

"No se encontró grabador de audio"

"No se pudo redimensionar la captura (Photon no disponible)"

El modo en vivo no se activa con la voz

Las imágenes son demasiado grandes / demasiado costosas

El STT transcribe incorrectamente

El TTS habla demasiado lento / con la voz equivocada

1 · On-demand vision (`/see`)

2 · Push-to-talk (`/voice`)

3 · Live hands-free mode (`/vision live on`)

1 · Visión bajo demanda (`/see`)

2 · Pulsar para hablar (`/voice`)

3 · Modo manos libres en vivo (`/vision live on`)