El harness del agente
Perch ejecuta un harness de agente completo en Desktop y en la CLI: shell, búsqueda, edición de archivos, trabajos en segundo plano, un sandbox sellado, modo Plan y permisos por nivel de riesgo. Aquí está el conjunto completo de herramientas y los controles que lo rigen.
Debajo del trabajo con documentos y las auditorías, Perch es un harness de agente de uso general. Ejecuta comandos, busca y edita archivos, crea agentes auxiliares y ejecuta código en un sandbox. La misma maquinaria que concilia un libro contable puede refactorizar un módulo, porque es la misma maquinaria.
Esta página es la referencia de lo que Perch realmente puede hacer en tu computadora y de los controles que deciden cuánto de eso ocurre sin preguntarte primero.
Solo en Desktop y la CLI
Shell y búsqueda
| Herramienta | Qué hace |
|---|---|
bash | Ejecuta comandos de shell en el espacio de trabajo. |
grep | Busca en el contenido de los archivos de la carpeta. |
glob | Encuentra archivos por patrón. |
La búsqueda se ejecuta con grep y glob reales y no como una suposición semántica, así que encontrar cada lugar donde se llama algo significa encontrarlos todos.
Lectura y escritura de archivos
| Herramienta | Qué hace |
|---|---|
readLocalFile | Lee un archivo y lo pone en el contexto. |
writeLocalFile | Escribe un archivo. |
editLocalFile | Edita parte de un archivo en su lugar. |
moveLocalFile, copyLocalFile | Mueve o copia. |
createDirectory, deleteLocalFile | Crea directorios, elimina archivos. |
statPath | Inspecciona una ruta sin leerla. |
Cada llamada se valida contra las raíces aprobadas de tu espacio de trabajo, así Perch no puede salir de la carpeta que abriste.
Trabajos en segundo plano
El trabajo largo no tiene por qué bloquear la conversación. Perch puede iniciar un comando en segundo plano y seguir adelante.
| Herramienta | Qué hace |
|---|---|
run_in_background | Inicia un comando como un trabajo independiente. |
check_background_task | Revisa cómo va. |
list_background_tasks | Muestra lo que se está ejecutando. |
wait_for_background_task | Espera hasta que termine. |
kill_background_task | Lo detiene. |
Esto es lo que convierte una suite de pruebas, una compilación o una instalación larga en algo que Perch puede supervisar en lugar de quedarse atrapado dentro.
El sandbox
Para el trabajo que necesita cálculos reales en lugar de razonar sobre cifras, Perch escribe código y lo ejecuta en un sandbox sellado con run_sandbox_code. Así es como un total se calcula en lugar de adivinarse.
El sandbox está reforzado de forma deliberada:
- Red desactivada. El sandbox no tiene acceso de salida.
- Seatbelt de macOS. La ejecución corre bajo un perfil de
sandbox-exec, aislada del resto de tu computadora. - Procedencia registrada. Las ejecuciones del sandbox quedan registradas, así una cifra calculada se puede rastrear hasta el código que la produjo.
Planificación y seguimiento de tareas
Perch tiene planificación de primera clase, no una simple instrucción de "pensar paso a paso":
- El modo Plan permite que Perch inspeccione el espacio de trabajo y redacte un plan, con las herramientas que modifican cosas bloqueadas hasta que lo apruebes. Recibes una tarjeta con el plan, y no se escribe nada mientras la lees.
- Las tareas pendientes (to-dos) permiten que Perch mantenga una lista de tareas visible durante una ejecución larga, así puedes ver el avance en lugar de adivinarlo.
- Preguntas. Cuando Perch realmente está bloqueado por una decisión que te toca a ti, pregunta en lugar de elegir por ti.
Modos de chat
El cuadro de mensaje tiene tres modos, y cambian lo que un turno tiene permitido hacer:
| Modo | Comportamiento |
|---|---|
| Ask | Conversación. Pregunta sobre la carpeta, los archivos subidos o qué hacer después. |
| Plan | Perch inspecciona, redacta un plan y espera la aprobación antes de actuar. |
| Agents | Perch planea y ejecuta la tarea. |
Modos de permisos
Aparte del modo de chat, un ajuste de permisos determina cuánto se ejecuta sin aprobación. Funciona por niveles de riesgo y no como un simple interruptor de encendido y apagado:
| Modo | Qué se ejecuta sin preguntar |
|---|---|
| Default | Nada riesgoso. Las escrituras, los comandos, los envíos, las eliminaciones y otras acciones irreversibles requieren aprobación. |
| Auto Review | El trabajo reversible de riesgo bajo y medio se ejecuta por su cuenta. Cada acción con consecuencias más allá de eso la revisa un revisor aparte, que te pregunta solo cuando no está seguro. |
| Take the Wheel | Autonomía total. Perch puede escribir, eliminar, enviar y realizar acciones irreversibles en el mundo real sin preguntar. |
| Plan | Solo lectura. Las herramientas que modifican cosas siguen bloqueadas hasta que se apruebe un plan. |
Auto Review funciona sin intervención pero no a ciegas: las ediciones reversibles y los comandos propios del proyecto avanzan, las acciones con consecuencias se revisan antes de ejecutarse y las de mayor riesgo (force pushes, eliminaciones masivas) siempre se detienen para que decidas tú. La línea que traza está entre lo reversible y lo irreversible, no entre lo fácil y lo difícil, así que editar un archivo que puedes deshacer se trata de forma distinta a enviar un correo. Consulta modos de permisos para ver cómo decide el revisor.
Esfuerzo
El control de esfuerzo define qué tanto trabaja el modelo en un turno. Es una barra de cinco segmentos: cuatro niveles de esfuerzo y, aparte, una muesca para Flock.
| Ajuste | Qué significa |
|---|---|
| Off | Sin razonamiento. Lo más rápido y lo que menos consume de tu uso. |
| Low | Razonamiento superficial. Tareas cortas y acotadas donde importa la velocidad. |
| Medium | Equilibrado. Menos llamadas a herramientas y más consolidadas. |
| High | Predeterminado. Razonamiento complejo y trabajo agéntico. |
| Flock | No es un nivel de esfuerzo. Planea un equipo de workers y los ejecuta en paralelo. Ideal para trabajos grandes que se pueden dividir. |
Lo interesante está por debajo. Los proveedores expresan el razonamiento de formas completamente distintas: algunos modelos ignoran por completo los parámetros de razonamiento, otros aceptan un solo interruptor de encendido y apagado, y otros exponen su propia escala con nombres. Cada modelo del catálogo de modelos declara a cuál de esos tipos pertenece, y el esfuerzo que eliges se ajusta al modelo que realmente se asignó para el turno.
Eso significa que un mismo control se comporta de forma coherente sin importar a qué modelo te enrutó Roost o cuál fijaste a mano. La barra nunca le promete a un modelo algo que no puede hacer.
Claude Opus 5.5 en Pro es un modelo con su propia escala: sus niveles de esfuerzo son low, medium, high, xhigh y max, y el razonamiento siempre está activado, así que no hay Off.
Gemini 4 Argon en Pro acepta Low, Medium y High. Siempre razona, así que Off funciona como Low.
Subagentes
Perch puede crear agentes auxiliares durante un turno, y tú eliges en qué modelo se ejecutan. El valor predeterminado es Inherit, que sigue al modelo que hace el trabajo principal. Elegir otro modelo es la forma de lograr que un modelo revise el trabajo de otro en lugar de calificar el suyo propio.
Este ajuste también cubre a los agentes delegados en segundo plano. Un modelo elegido por nombre cuesta más que dejar el enrutamiento en automático.
Consulta Subagentes para ver el panorama completo, y Operador y agentes para ver en qué se diferencian los cuatro modos multiagente.
Skills
Perch incluye un paquete de skills de operador que se cargan solo cuando son relevantes: navegación del espacio de trabajo, GitHub y git, documentos, hojas de cálculo, presentaciones, PDF, diagramas, investigación, calidad de datos y operación del navegador. Cada una es un conjunto de instrucciones más herramientas preferidas para un tipo de trabajo, y sus metadatos son baratos de revisar, mientras que las instrucciones completas se cargan solo cuando hay coincidencia.
Cada skill también incluye un estándar de verificación, que es lo que tiene que confirmar antes de entregarte un resultado. Consulta Skills para ver el paquete completo y cómo se selecciona cada una.
Reglas del proyecto
Perch lee instrucciones permanentes de tu carpeta en cada turno, desde .perch/PERCH.md y .perch/rules/, además de un manual global en ~/Documents/Perch/PERCH.md. Las reglas que pongas ahí tienen prioridad sobre los valores predeterminados de Perch.
Consulta Memoria para ver cómo encajan los archivos del proyecto, la memoria duradera y el aprendizaje a partir de correcciones.
Cómo funciona Perch
Perch primero lee tu material, fundamenta su respuesta en lo que encontró y muestra la fuente detrás de cada afirmación.
Skills
Perch incluye un paquete de skills de operador que se cargan solo cuando son relevantes. Cada una es un conjunto de reglas de trabajo, herramientas preferidas y un estándar de verificación para un tipo de trabajo. Aquí verás qué viene incluido y cómo se elige cada una.