Ferret
Español
Discord (se abre en una pestaña nueva) X (se abre en una pestaña nueva) GitHub (se abre en una pestaña nueva) Descargar

Uso de Ferret

Enviar a agentes

Ejecuta tu agente de programación en la terminal integrada y pásale una revisión con un clic. Claude Code y Codex son los ejemplos habituales, pero sirve cualquier agente de la lista de abajo, y también un CLI que añadas tú. También puedes copiar la instrucción para un agente que se ejecute en otro sitio, o publicar la revisión en GitHub.

#Revisar los hallazgos

Cada tarjeta de la pestaña Hallazgos permite:

  • Editar directamente el título y la petición
  • Alternar Enviar / No enviar
  • Ver grabación (salta a ese momento) y Reemplazar imagen (elegir otro fotograma)
  • Confirmar / Marcar como pendiente de revisión, Combinar con el siguiente, Eliminar

Filtrar por progreso muestra u oculta hallazgos según su estado (por ejemplo, Solo los que esperan tu revisión); Mostrar todo quita el filtro.

La cabecera tiene Deshacer, Abrir carpeta, Copiar para el agente, Enviar a GitHub / GitLab, Organizar y Enviar al agente. Lo que dijiste y no se convirtió en hallazgo aparece en Voz excluida, donde Restaurar como hallazgo lo recupera.

La pestaña Hallazgos
La pestaña Hallazgos

#Ejecutar agentes en la terminal integrada

Al abrir un proyecto, Ferret inicia una pestaña de terminal por cada agente de Ajustes → Agentes → Iniciar al abrir un proyecto, en la carpeta del proyecto y en el modo normal del agente. De forma predeterminada son Claude Code y Codex:

claude
codex

En su lugar puedes elegir cualquier agente de la lista de compatibles (se inician en el orden en que los eliges) o ninguno.

Las solicitudes de permiso siguen activas

Registrar o clonar un proyecto no hace que Ferret confíe en él. Agentes como Claude Code y Codex preguntan la primera vez si confías en la carpeta, y siguen preguntando antes de editar archivos o ejecutar comandos. Para que los agentes omitan las solicitudes de permiso, las aprobaciones y el sandbox en un proyecto de confianza, actívalo para ese proyecto en Ajustes → Agentes → Omitir las solicitudes de permiso y confirma. Ferret añade la opción de omisión propia de cada agente cuando se conoce; los agentes sin una opción conocida mantienen sus solicitudes. Después solo se aplica a los agentes que abres tú en la carpeta de ese proyecto; los agentes que se inician al abrir el proyecto siempre mantienen sus solicitudes. Las opciones de omisión de permisos escritas en los argumentos se ignoran.

Si no hay ningún agente seleccionado, se abre una shell normal. El menú + abre una Nueva terminal, inicia cualquiera de tus agentes en una pestaña nueva o lleva a Ajustes de agentes…. Su cuadro de búsqueda también encuentra pestañas, URL guardadas y archivos.

Las pestañas muestran el estado del agente: En ejecución, Esperando entrada, Terminado (sin leer), Inactivo. En la barra lateral se marcan los proyectos con un agente en ejecución, así que lo ves sin cambiar de proyecto.

Arrastrar pestañas y paneles de terminal para dividirlos, moverlos y volver a convertirlos en pestañas.

Arrastrar para dividir. Arrastra una pestaña, o un panel por su asa (aparece cuando una pestaña está dividida), y suéltala:

  • en el cuarto exterior del borde de un panel: Dividir a la izquierda / Dividir a la derecha / Dividir hacia arriba / Dividir hacia abajo
  • en el centro de un panel: Abrir como pestaña (un panel sale de su división y pasa a ser una pestaña propia)
  • en la franja fina alrededor de toda el área de terminal: Dividir toda el área a la izquierda, etc. (cuando hay 2 o más paneles)
  • en la barra de pestañas: Colocar aquí como pestaña

Los procesos siguen ejecutándose mientras los mueves, y una pestaña que se queda vacía se cierra. Divisiones con el teclado:

AcciónmacOSWindows / Linux
Nueva terminal⌘TCtrlT
Dividir a la derecha⌘DCtrlShiftD
Dividir hacia abajo⌘⇧DAltShiftD
Cerrar panel / pestaña⌘WCtrlW

#Agentes compatibles

Ferret no está atado a un solo agente. Reconoce los agentes de programación de abajo: puede iniciarlos, detectarlos en una terminal para Enviar al agente y mostrar si están instalados. Ajustes → Agentes los muestra con Instalado / No encontrado, un botón Instalar cuando el fabricante publica un instalador de una línea, y el comando y los argumentos de cada uno.

¿No está en la lista? Ajustes → Agentes → Añadir agente personalizado registra cualquier CLI o script envoltorio (un nombre, un comando y, opcionalmente, el nombre de proceso con el que se reconoce), o añádelo a agents.customAgents en settings.json. Los agentes que se ejecutan fuera de Ferret pueden usar Copiar para el agente.

Algunas funciones dependen del agente y por ahora se limitan a Claude Code y Codex:

  • Cuentas y uso: cambiar entre varios inicios de sesión y el medidor de límite de uso del pie de la ventana.
  • Organizar: se ejecuta con tu sesión de Claude Code o Codex, o con una API de LLM que configures.

#Enviar al agente / Copiar para el agente

De la pestaña Hallazgos al agente de la terminal integrada con Enviar al agente.
  1. Haz clic en Enviar al agente. De forma predeterminada (Automático (pestaña actual o un agente en marcha)) se envía al agente de la pestaña de terminal actual o a uno en marcha. Usa la flecha junto al botón (Elige el agente al que enviar) para elegir un agente o una pestaña concretos.
  2. Ferret escribe la instrucción en la entrada del agente y la envía. Sigue el progreso en la terminal.

Si no hay ningún agente en marcha, Ferret inicia uno primero y envía en cuanto está listo. No se envía nada mientras el agente espera una respuesta a una solicitud de permiso. Responde primero en la terminal.

Copiar para el agente pone la misma instrucción en el portapapeles para un agente que se ejecute en otro sitio (otra terminal, un IDE u otra app). Solo se incluyen los hallazgos marcados como Enviar. El vídeo nunca se incluye.

#Comprobación de aceptación con un modelo de decisión

El agente corrige los hallazgos y comprueba cada uno con el modelo de decisión hasta que todos pasan.

Actívala y tu agente de programación comprobará su propio trabajo frente a cada hallazgo antes de informar de que está hecho. Ferret no juzga nada por sí mismo: da al agente un modelo de decisión (cualquier API compatible con System One) y le indica, en feedback.md, que repita hasta que todos los hallazgos pasen.

  1. El agente implementa los hallazgos.
  2. Para cada hallazgo captura una screenshot AFTER (mismo viewport y mismo estado de la página que la imagen BEFORE) y envía al modelo de decisión una solicitud con el texto del hallazgo, su línea «Done when» y las imágenes BEFORE/AFTER.
  3. Un hallazgo pasa cuando P(done) es al menos el umbral (0.7 de forma predeterminada) y la elección es done. El agente corrige el resto y vuelve a juzgar todos los hallazgos en cada ronda, y solo se detiene cuando todos pasan en la misma ronda, o por un motivo honesto que debe indicar: la API no responde, un hallazgo está fuera de alcance o un hallazgo está atascado con las puntuaciones sin cambios.
  4. La lista final de Hecho / No hecho incluye las puntuaciones de cada hallazgo y el número de rondas.

Configúrala en Ajustes → Modelo de decisión y activa Añadir la comprobación con modelo de decisión a las instrucciones del agente. Los preajustes solo rellenan los campos; todos los campos siguen siendo editables, y Personalizado funciona con cualquier API compatible.

PreajusteURL de la solicitudModelosClave
Ollama (predeterminado)http://localhost:11434/v1/systemoneclef-flash, clef (leen imágenes); nimble, tev1 (solo texto)ninguna, gratis
Cloudflare Workers AIhttps://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/cloudflare/{model}clef-flash, clef (leen imágenes)CLOUDFLARE_API_TOKEN (permiso de Workers AI); ID de cuenta del campo o de CLOUDFLARE_ACCOUNT_ID
Vercel AI Gatewayhttps://ai-gateway.vercel.sh/typesafe/v1/systemonetypesafe-ai/jev, convaiinnovations/laya (solo texto)AI_GATEWAY_API_KEY
TypeSafehttps://api.typesafe.ai/v1/systemonejev-latest, jev-preview (solo texto)TYPESAFE_API_KEY
Personalizadocualquier URL completacualquieraBearer, una cabecera personalizada o ninguna; se admiten cabeceras adicionales

Para Ollama, instálalo (0.35.1 o posterior para Clef / Clef Flash) y descarga el modelo en una terminal. Ferret no ejecuta instaladores:

ollama pull clef-flash

Las claves se toman del campo de clave (guardada con tus otras claves de API), de una variable de entorno que indiques (el entorno de la app, el .env del proyecto o ~/.ferret/.env) o de apiKey en settings.json. Las cabeceras adicionales pueden leer valores de variables de entorno con ${VAR}.

Cómo se mantiene la clave fuera de los prompts

Los agentes nunca ven tu clave. Ferret ejecuta un relay local en 127.0.0.1 y da a cada terminal FERRET_DECISION_URL (el relay, con un token por terminal), FERRET_DECISION_MODEL y FERRET_DECISION_IMAGES (durante una versión también se definen los nombres antiguos MOVIE_ADE_DECISION_*). El relay añade la clave y las cabeceras y reenvía la solicitud sin cambios, así que los prompts, feedback.md y las transcripciones de los agentes no contienen secretos. Las terminales abiertas después de cambiar los ajustes los aplican.

Cloudflare se diferencia de la documentación de System One en dos cosas (comprobado con la API real): las imágenes deben ser data URI (data:image/jpeg;base64,…; si no, 422 "image must be an embedded base64 data URI"), y la respuesta viene envuelta como { "result": { … }, "success": true } (los errores llegan como { "success": false, "errors": [ … ] }). El preajuste de Cloudflare pone Codificación de imágenes en data URI, los agentes lo reciben como FERRET_DECISION_IMAGE_FORMAT y las instrucciones les dicen que lean .result cuando exista. El relay deja pasar ambas direcciones sin cambios. Para usar una Global API Key en lugar de un API token, pon Autenticación en Sin clave y añade las cabeceras X-Auth-Email: ${CLOUDFLARE_EMAIL} y X-Auth-Key: ${CLOUDFLARE_API_KEY}.

Solo Clef y Clef Flash leen imágenes. Con un modelo solo de texto, desactiva Enviar imágenes BEFORE/AFTER; el agente juzga entonces solo con texto, lo que es menos fiable.

Ollama e imágenes grandes

Ollama 0.35.0 limita las solicitudes a /v1/systemone a 64 KiB, así que las solicitudes con capturas fallan con HTTP 413. Las instrucciones indican al agente que reduzca ambas imágenes a un máximo de 1024px de ancho en JPEG (calidad de unos 70). Si aun así recibe 413, actualiza Ollama a 0.35.1 o posterior, o cambia a Cloudflare Workers AI.

#Uso de la API en el pie de la ventana

Las llamadas de decisión pasan por el relay, así que Ferret puede contarlas. El elemento del pie situado junto al medidor de uso del agente muestra el modelo de decisión y las llamadas, los tokens y el coste de hoy (por ejemplo clef-flash · 42 calls · 18.3k tok). Haz clic para ver hoy, este mes, por proyecto, por modelo y por tipo (decisión / transcripción / organización), y las últimas 50 llamadas.

El coste solo aparece cuando la API lo informa (Vercel AI Gateway lo hace) o cuando defines precios por 1M de tokens en Ajustes → Modelo de decisión; si no, se muestra "—". Solo se registran metadatos (hora, proyecto, modelo, estado, latencia, tamaño, número de imágenes, tokens, coste), nunca imágenes, texto ni claves, en ~/.ferret/usage/decision-YYYY-MM.jsonl, un archivo por mes.

#Personalizar la instrucción

Edita Ajustes → Agentes → Instrucciones para el agente. Se expanden dos variables:

VariableSe expande a
{{path}}Ruta absoluta de feedback.md
{{relpath}}Ruta relativa al proyecto: .ferret/reviews/<id>/feedback.md

Déjala vacía para usar la predeterminada. La longitud máxima es de 2000 caracteres, y Restablecer instrucciones recupera la predeterminada. Ejemplo:

Read {{relpath}} and the PNGs next to it. Fix only findings marked to send, one commit per finding, then run the tests.

El ajuste se guarda como agentPrompt en settings.json.

#Enviar a GitHub o GitLab (Issue / comentario en PR o MR)

Enviar a GitHub publica la revisión como un issue nuevo o como un comentario en una de tus pull requests abiertas. La autenticación se delega en GitHub CLI (se abre en una pestaña nueva). Ferret nunca lee ni guarda un token.

  1. Instala gh: brew install gh (macOS), winget install --id GitHub.cli (Windows), o consulta cli/cli (se abre en una pestaña nueva).
  2. Ajustes → GitHub / GitLab → Iniciar sesión en la terminal ejecuta gh auth login --web -h github.com en la terminal integrada.
  3. Haz clic en Enviar a GitHub, elige Crear un Issue nuevo o una PR, y revisa el Título y el Cuerpo (editables).
  4. Marca la casilla de confirmación y luego Crear Issue o Publicar comentario.

Detalles:

  • El repositorio se obtiene de git remote get-url origin.
  • Ferret ejecuta gh issue create --repo … --title … --body-file - o gh pr comment <n> --repo … --body-file -.
  • El cuerpo es feedback.md sin las líneas de imagen (las imágenes no se suben), hasta 60.000 caracteres.
  • Las PR candidatas son tus propias PR abiertas (hasta 30).

Si GH_TOKEN o GITHUB_TOKEN están definidos, gh los usa primero, y el panel de ajustes avisa de ello.

GitLab. Cuando origin es un proyecto de GitLab (gitlab.com o un GitLab autogestionado), el mismo botón envía a GitLab mediante GitLab CLI (se abre en una pestaña nueva) (glab): un issue nuevo o un comentario en una de tus merge requests abiertas. Inicia sesión con Ajustes → GitHub / GitLab, que ejecuta glab auth login (con --hostname para un GitLab autogestionado) en la terminal integrada. Ferret nunca lee ni guarda el token, y avisa cuando GITLAB_TOKEN está definido.

Petición de estrella. Después de tu primer Enviar al agente, y cuando llegas a 3, 10 y 30 revisiones terminadas, Ferret puede pedirte que le des una estrella en GitHub. Lo pide como máximo 3 veces, con al menos 3 días de separación, y nunca mientras grabas. Dar estrella en GitHub da la estrella mediante tu propia sesión de gh (o abre GitHub si gh no está disponible), y No volver a preguntar detiene las peticiones. También puedes dar la estrella desde Ayuda → Dar una estrella a Ferret en GitHub.

#Instalar herramientas CLI e iniciar sesión

Ajustes → Herramientas CLI muestra las herramientas de línea de comandos que tus agentes suelen necesitar, indica cuáles están instaladas y su versión, y ejecuta el comando oficial de instalación o de inicio de sesión para tu sistema operativo en una pestaña de terminal nueva:

  • Alojamiento Git: gh, glab
  • IA y modelos: Ollama, Cloudflare wrangler
  • Despliegue: Vercel, Netlify, Fly.io, Railway, Heroku
  • Nube y servicios: Supabase, Firebase, Stripe, Google Cloud (gcloud), AWS, Azure, Docker

Cuando una herramienta no tiene un instalador oficial de una línea para tu sistema operativo, Documentación abre su página de instalación. La lista se vuelve a comprobar sola cuando termina una instalación.

Ayuda a traducir esta página en GitHub (se abre en una pestaña nueva)