Serena

:rocket: Serena es un poderoso kit de herramientas de agente de codificación capaz de convertir un LLM en un agente con todas las funciones que trabaja directamente en su base de código .
:wrench: Serena proporciona herramientas esenciales de recuperación y edición de código semántico que son similares a las capacidades de un IDE, extrayendo entidades de código a nivel de símbolo y explotando la estructura relacional.
:free: Serena es gratuita y de código abierto , lo que mejora las capacidades de los LLM a los que ya tienes acceso de forma gratuita.

Demostración

Aquí se muestra una demostración de cómo Serena implementa una pequeña función (una mejor interfaz gráfica de usuario de registro) con Claude Desktop. Observe cómo las herramientas de Serena permiten a Claude encontrar y editar los símbolos adecuados.

https://github.com/user-attachments/assets/6eaa9aa1-610d-4723-a2d6-bf1e487ba753

Integración de LLM

Serena proporciona las herramientas necesarias para codificar flujos de trabajo, pero se requiere un LLM para realizar el trabajo real y orquestar el uso de las herramientas.

Serena se puede integrar con un LLM de varias maneras:

mediante el uso del protocolo de contexto de modelo (MCP) .
Serena proporciona un servidor MCP que se integra con
- Claude Desktop,
- IDE como VSCode, Cursor o IntelliJ,
- Extensiones como Cline o Roo Code
- Goose (para una buena experiencia CLI)
- y muchos otros, incluida la aplicación ChatGPT próximamente
mediante el uso de Agno, el marco de agente agnóstico del modelo .
El agente basado en Agno de Serena le permite convertir prácticamente cualquier LLM en un agente de codificación, ya sea proporcionado por Google, OpenAI o Anthropic (con una clave API paga) o un modelo gratuito proporcionado por Ollama, Together o Anyscale.
incorporando las herramientas de Serena en un marco de agente de su elección.
La implementación de la herramienta Serena está desacoplada del código específico del marco y, por lo tanto, se puede adaptar fácilmente a cualquier marco de agente.

Compatibilidad con lenguajes de programación y capacidades de análisis semántico

Las capacidades de análisis de código semántico de Serena se basan en servidores de lenguaje que utilizan el protocolo de servidor de lenguaje (LSP), ampliamente implementado. El LSP proporciona un conjunto versátil de funcionalidades de consulta y edición de código basadas en la comprensión simbólica del código. Equipada con estas capacidades, Serena descubre y edita código como lo haría un desarrollador experimentado que utiliza las capacidades de un IDE. Serena puede encontrar eficientemente el contexto adecuado y hacer lo correcto incluso en proyectos muy grandes y complejos. Por lo tanto, no solo es gratuito y de código abierto, sino que a menudo logra mejores resultados que las soluciones existentes de pago.

Los servidores de idiomas ofrecen compatibilidad con una amplia gama de lenguajes de programación. Con Serena, ofrecemos...

Soporte directo y listo para usar para:
- Pitón
- Java ( Nota : el inicio es lento, especialmente el inicio inicial)
- Mecanografiado
Soporte indirecto (puede requerir algunos cambios de código/instalación manual) para:
- Ruby (no probado)
- Ir (no probado)
- C# (no probado)
- Óxido (no probado)
- Kotlin (no probado)
- Dart (no probado)
- C/C++ (sin probar). Estos lenguajes son compatibles con la biblioteca de servidor de lenguajes multilspy , que Serena utiliza internamente. Sin embargo, no probamos explícitamente si la compatibilidad con estos lenguajes funciona realmente.

En principio, se pueden soportar fácilmente más idiomas proporcionando un adaptador superficial para una nueva implementación del servidor de idiomas.

Tabla de contenido

¿Para qué puedo utilizar Serena?
Agentes de codificación gratuitos con Serena
Inicio rápido
Herramientas y configuración de Serena
Comparación con otros agentes de codificación
Incorporación y recuerdos
Combinación con otros servidores MCP
Recomendaciones sobre el uso de Serena
Solución de problemas
- Registro de Serena
Expresiones de gratitud
Personalización de Serena
Lista completa de herramientas

¿Para qué puedo utilizar Serena?

Puede usar Serena para cualquier tarea de codificación, ya sea centrada en el análisis, la planificación, el diseño de nuevos componentes o la refactorización de los existentes. Dado que las herramientas de Serena permiten que un LLM cierre el ciclo cognitivo de percepción-acción, los agentes basados en Serena pueden realizar tareas de codificación de forma autónoma de principio a fin, desde el análisis inicial hasta la implementación, las pruebas y, finalmente, la confirmación del sistema de control de versiones.

Serena puede leer, escribir y ejecutar código, así como leer registros y la salida del terminal. Si bien no lo recomendamos necesariamente, la programación con vibración es posible, y si desea sentir que el código ya no existe, Serena podría ser incluso más adecuada para la vibración que un agente dentro de un IDE (ya que dispondrá de una interfaz gráfica de usuario independiente que le permitirá olvidarse por completo).

Agentes de codificación gratuitos con Serena

Incluso la versión gratuita de Claude de Anthropic es compatible con servidores MCP, por lo que puedes usar Serena con Claude gratis. Probablemente, pronto será posible hacer lo mismo con ChatGPT Desktop una vez que se incorpore la compatibilidad con servidores MCP.
A través de Agno, además tienes la opción de utilizar Serena con un modelo de pesas libres/abiertas.

Serena es la contribución de Oraios AI a la comunidad de desarrolladores.
Nosotros mismos lo utilizamos habitualmente.

Nos cansamos de tener que pagar varias suscripciones basadas en IDE (como Windsurf o Cursor), lo que nos obligaba a seguir comprando tokens además de los costos de suscripción de chat que ya teníamos. Los altos costos de API de herramientas como Claude Code, Cline, Aider y otras herramientas basadas en API son igualmente poco atractivos. Por lo tanto, creamos Serena con la posibilidad de cancelar la mayoría de las demás suscripciones.

Inicio rápido

Serena se puede utilizar de varias maneras, a continuación encontrará instrucciones para integraciones seleccionadas.

Si solo desea convertir a Claude en un agente de codificación de uso gratuito, le recomendamos utilizar Serena a través de Claude Desktop.
Si quieres usar Gemini o cualquier otro modelo y quieres una interfaz gráfica, deberías usar Agno . En macOS, también puedes usar la interfaz gráfica de Goose .
Si prefieres usar Serena mediante una CLI, puedes usar goose . En este caso, prácticamente cualquier modelo es compatible.
Si desea utilizar Serena integrado en su IDE, consulte la sección sobre otros clientes MCP .

Configuración y configuración

Instalar uv (instrucciones aquí )
Clonar el repositorio en /path/to/serena .
Copie serena_config.template.yml a serena_config.yml y ajuste la configuración.
Copia myproject.template.yml en myproject.yml y ajusta la configuración específica de tu proyecto. (Agrega un archivo de este tipo por cada proyecto en el que quieras que Serena trabaje).
Si desea que Serena cambie dinámicamente entre proyectos, agregue la lista de todos los archivos de proyecto creados en el paso anterior a la lista projects en serena_config.yml .

⚠️ Nota: Serena se encuentra en desarrollo activo. Añadimos funciones continuamente, mejoramos la estabilidad y la experiencia de usuario (UX). Por lo tanto, la configuración puede cambiar de forma perjudicial. Si su configuración no es válida, el servidor MCP o el agente basado en Serena podrían no iniciarse (consulte los registros de MCP en el primer caso). Consulte el registro de cambios y las plantillas de configuración al actualizar Serena y adapte sus configuraciones según corresponda.

Después de la configuración inicial, continúe con una de las secciones siguientes, dependiendo de cómo desee utilizar Serena.

Servidor MCP (Claude Desktop)

Cree un archivo de configuración para su proyecto, digamos myproject.yml basado en la plantilla en myproject.template.yml .
Configure el servidor MCP en su cliente.
Para Claude Desktop (disponible para Windows y macOS), vaya a Archivo / Configuración / Desarrollador / Servidores MCP / Editar configuración. Esto le permitirá abrir el archivo JSON claude_desktop_config.json . Agregue lo siguiente (con las rutas ajustadas) para habilitar Serena:
{ "mcpServers": { "serena": { "command": "/abs/path/to/uv", "args": ["run", "--directory", "/abs/path/to/serena", "serena-mcp-server", "--project-file", "/abs/path/to/myproject.yml"] } } }
:info: pasar el archivo del proyecto es opcional si ha configurado enable_project_activation , ya que esta configuración le permitirá simplemente indicarle a Claude que active el proyecto en el que desea trabajar.Si está utilizando rutas que contienen barras invertidas para rutas en Windows (tenga en cuenta que también puede usar barras diagonales), asegúrese de escaparlas correctamente ( \\ ).

¡Listo! Guarda la configuración y reinicia Claude Desktop.

Nota: en Windows y macOS hay aplicaciones oficiales de Claude Desktop de Anthropic, para Linux hay una versión comunitaria de código abierto .

⚠️ Asegúrate de salir por completo de la aplicación Claude Desktop, ya que cerrar Claude simplemente la minimizará en la bandeja del sistema, al menos en Windows.

Después de reiniciar, deberías ver las herramientas de Serena en tu interfaz de chat (observa el pequeño ícono del martillo).

⚠️ Nombres de herramientas: Claude Desktop (y la mayoría de los clientes MCP) no resuelven el nombre del servidor. Por lo tanto, no debería decir algo como "usar las herramientas de Serena". En su lugar, puede indicarle al LLM que use herramientas simbólicas o una herramienta específica haciendo referencia a su nombre. Además, si utiliza varios servidores MCP, podría experimentar conflictos de nombres de herramientas que provoquen un comportamiento indefinido. Por ejemplo, Serena actualmente es incompatible con el servidor MCP del sistema de archivos debido a conflictos de nombres de herramientas.

Tenga en cuenta que los servidores MCP que utilizan stdio como protocolo son algo inusuales en cuanto a arquitecturas cliente/servidor, ya que el cliente debe iniciar el servidor para que la comunicación se realice a través de su flujo de entrada/salida estándar. En otras palabras, no necesita iniciar el servidor usted mismo. La aplicación cliente (p. ej., Claude Desktop) se encarga de esto y, por lo tanto, debe configurarse con un comando de inicio.

Para obtener más información sobre los servidores MCP con Claude Desktop, consulte la guía de inicio rápido oficial .

Otros clientes MCP: Cline, Roo-Code, Cursor, Windsurf, etc.

Al ser un servidor MCP, Serena puede incluirse en cualquier cliente MCP. La misma configuración anterior, con pequeñas modificaciones específicas para cada cliente, debería funcionar. La mayoría de los asistentes de programación populares (extensiones IDE o IDE similares a VSCode) permiten la conexión a servidores MCP. Incluir Serena generalmente mejora su rendimiento al proporcionarles herramientas para operaciones simbólicas.

En este caso, la facturación por uso sigue estando a cargo del cliente que usted elija (a diferencia del cliente Claude Desktop). Sin embargo, es posible que aún desee usar Serena con este enfoque, por ejemplo, por alguna de las siguientes razones:

Ya estás utilizando un asistente de codificación (por ejemplo, Cline o Cursor) y solo quieres hacerlo más potente.
Estás en Linux y no quieres usar el escritorio Claude creado por la comunidad
Quiere una integración más estrecha de Serena en su IDE y no le importa pagar por ello

Aquí también se aplican las mismas consideraciones que al utilizar Serena para Claude Desktop (en particular, colisiones de nombres de herramientas).

Al usar Serena en un IDE o extensión con interacciones de IA integradas para programación (que, en realidad, son todas), el conjunto completo de herramientas de Serena puede generar interacciones no deseadas con las herramientas internas del cliente, sobre las que el usuario podría no tener control. Esto aplica especialmente a las herramientas de edición, que quizás desee desactivar para este propósito. A medida que adquiramos más experiencia con Serena en los diversos clientes populares, recopilaremos y mejoraremos las mejores prácticas para garantizar una experiencia fluida.

Ganso

Goose es un agente de codificación independiente que se integra con servidores MCP y ofrece una interfaz de línea de comandos (CLI) (y una interfaz gráfica de usuario en macOS). Usar Goose es actualmente la forma más sencilla de ejecutar Serena mediante una CLI con un LLM de su elección.

Siga las instrucciones aquí para instalarlo.

Después, usa goose configure para agregar una extensión. Para agregar Serena, elige la opción Command-line Extension , nómbrala Serena y agrega el siguiente comando:

/abs/path/to/uv run --directory /abs/path/to/serena serena-mcp-server /optional/abs/path/to/project.yml

Dado que Serena puede realizar todas las operaciones de edición y comandos necesarias, debes desactivar la extensión developer que Goose habilita por defecto. Para ello, ejecuta

goose configure

Nuevamente, elija la opción Toggle Extensions y asegúrese de que Serena esté habilitada y la opción developer no.

Eso es todo. Revisa las opciones de configuración de Goose para ver qué puedes hacer con él (que son muchas, como configurar diferentes niveles de permisos para la ejecución de herramientas).

Goose no siempre termina correctamente los procesos de Python en servidores MCP al finalizar una sesión. Le recomendamos deshabilitar la interfaz gráfica de Serena o limpiar manualmente cualquier proceso de Python en ejecución después de terminar de trabajar con Goose.

Agente Agno

Agno es un framework de agente independiente del modelo que permite convertir Serena en un agente (independiente de la tecnología MCP) con una gran cantidad de LLM subyacentes. Actualmente, Agno es la forma más sencilla de ejecutar Serena en una interfaz gráfica de chat con el LLM que prefiera (a menos que use un Mac, en cuyo caso podría preferir Goose, que prácticamente no requiere configuración).

Aunque Agno aún no es completamente estable, lo elegimos porque cuenta con su propia interfaz de usuario de código abierto, lo que facilita el uso directo del agente mediante una interfaz de chat. Con Agno, Serena se convierte en un agente (ya no es un servidor MCP), lo que permite su uso programático (por ejemplo, para benchmarking o dentro de la aplicación).

Así es como funciona (ver también la documentación de Agno ):

Descargue el código del agente-ui con npx
npx create-agent-ui@latest
o, alternativamente, clonarlo manualmente:
git clone https://github.com/agno-agi/agent-ui.git cd agent-ui pnpm install pnpm dev
Instalar serena con los requisitos opcionales:
# You can also only select agno,google or agno,anthropic instead of all-extras uv pip install --all-extras -r pyproject.toml -e .
Copie .env.example a .env y complete las claves API para los proveedores que desee utilizar.
Inicie la aplicación agno agent con
uv run python scripts/agno_agent.py
De forma predeterminada, el script utiliza a Claude como modelo, pero puedes elegir cualquier modelo compatible con Agno (que es esencialmente cualquier modelo existente).
En una nueva terminal, inicie la interfaz de usuario de agno con
cd agent-ui pnpm dev
Conecta la interfaz de usuario al agente que iniciaste anteriormente y empieza a chatear. Tendrás las mismas herramientas que en la versión del servidor MCP.

A continuación se muestra una breve demostración de Serena realizando una pequeña tarea de análisis con el modelo Gemini más nuevo:

https://github.com/user-attachments/assets/ccfcb968-277d-4ca9-af7f-b84578858c62

⚠️ IMPORTANTE: A diferencia del enfoque del servidor MCP, la ejecución de herramientas en la interfaz de usuario de Agno no solicita permiso al usuario. La herramienta de shell es especialmente crítica, ya que puede ejecutar código arbitrario. Si bien nunca hemos tenido problemas con esto en nuestras pruebas con Claude, permitirlo podría no ser del todo seguro. Puede deshabilitar ciertas herramientas para su configuración en el archivo de configuración de su proyecto Serena ( .yml ).

Otros marcos de agentes

El agente Agno es particularmente bueno debido a la interfaz de usuario de Agno, pero es fácil incorporar Serena en cualquier marco de agente (como pydantic-ai , langgraph u otros).

Solo tienes que escribir un adaptador de las herramientas de Serena a las herramientas del framework de tu elección, tal como lo hicimos nosotros para agno en SerenaAgnoToolkit .

Herramientas y configuración de Serena

Serena combina herramientas para la recuperación de código semántico con funciones de edición y ejecución de shell. Encuentre la lista completa de herramientas a continuación .

Generalmente se recomienda el uso de todas las herramientas, ya que esto permite que Serena proporcione el mayor valor: solo ejecutando comandos de shell (en particular, pruebas) Serena puede identificar y corregir errores de forma autónoma.

Sin embargo, cabe destacar que la herramienta execute_shell_command permite la ejecución de código arbitrario. Al usar Serena como servidor MCP, los clientes suelen solicitar permiso al usuario antes de ejecutar una herramienta, por lo que, siempre que el usuario inspeccione los parámetros de ejecución previamente, esto no debería ser un problema. Sin embargo, si tiene dudas, puede deshabilitar ciertos comandos en el archivo de configuración .yml de su proyecto. Si solo desea usar Serena para analizar código y sugerir implementaciones sin modificar el código base, puede considerar deshabilitar las herramientas de edición en la configuración.

create_text_file
insert_after_symbol
insert_at_line
insert_before_symbol
replace_symbol_body
delete_lines .

En general, asegúrese de realizar una copia de seguridad de su trabajo y utilizar un sistema de control de versiones para evitar perder cualquier trabajo.

Comparación con otros agentes de codificación

Hasta donde sabemos, Serena es el primer agente de codificación con todas las funciones, donde toda la funcionalidad está disponible a través de un servidor MCP, por lo que no requiere claves API ni suscripciones.

Agentes de codificación basados en suscripción

Los agentes de programación por suscripción más destacados forman parte de IDE como Windsurf, Cursor y VSCode. La funcionalidad de Serena es similar a la del Agente de Cursor, la Cascada de Windsurf o el próximo modo de agente de VSCode.

Serena tiene la ventaja de no requerir suscripción. Una posible desventaja es que no está integrado directamente en un IDE, por lo que la inspección del código recién escrito no es tan fluida.

Las diferencias más técnicas son:

Serena no está vinculada a un IDE específico. El servidor MCP de Serena puede usarse con cualquier cliente MCP (incluidos algunos IDE), y el agente basado en Agno ofrece otras maneras de aplicar su funcionalidad.
Serena no está vinculada a un modelo de lenguaje grande o API específico.
Serena navega y edita código mediante un servidor de lenguaje, por lo que tiene una comprensión simbólica del código. Las herramientas basadas en IDE suelen utilizar un enfoque basado en RAG o puramente en texto, que suele ser menos potente, especialmente para bases de código extensas.
Serena es de código abierto y tiene una base de código pequeña, por lo que se puede ampliar y modificar fácilmente.

Agentes de codificación basados en API

Una alternativa a los agentes basados en suscripción son los agentes basados en API como Claude Code, Cline, Aider, Roo Code y otros, donde los costes de uso se corresponden directamente con los costes de la API del LLM subyacente. Algunos de ellos (como Cline) incluso pueden incluirse en IDEs como extensión. Suelen ser muy potentes y su principal desventaja son los costes de la API (potencialmente muy elevados).

Serena puede usarse como agente basado en API (véase la sección sobre Agno más arriba). Aún no hemos desarrollado una herramienta CLI ni una extensión IDE dedicada para Serena (y probablemente no sea necesaria, ya que Serena ya se puede usar con cualquier IDE compatible con servidores MCP). Si existe demanda de una herramienta CLI como Claude Code para Serena, consideraremos desarrollarla.

La principal diferencia entre Serena y otros agentes basados en API es que también puede utilizarse como servidor MCP, por lo que no requiere una clave API y evita los costes de la API. Esta es una característica única de Serena.

Otros agentes de codificación basados en MCP

Existen otros servidores MCP diseñados para codificación, como DesktopCommander y codemcp . Sin embargo, hasta donde sabemos, ninguno ofrece herramientas de recuperación y edición de código semántico; se basan exclusivamente en el análisis de texto. Es la integración de los servidores de lenguaje y el MCP lo que hace a Serena único y tan potente para tareas de codificación complejas, especialmente en el contexto de bases de código extensas.

Incorporación y recuerdos

De forma predeterminada, Serena realizará un proceso de incorporación al iniciar un proyecto por primera vez. El objetivo es que Serena se familiarice con el proyecto y guarde recuerdos que pueda utilizar en futuras interacciones.

Las memorias son archivos almacenados en .serena/memories/ , en el directorio del proyecto, que el agente puede leer. Puede leerlas y modificarlas según sea necesario; también puede agregar nuevas manualmente. Todos los archivos del directorio .serena/memories/ son archivos de memoria.

Descubrimos que los recuerdos mejoran significativamente la experiencia del usuario con Serena. Serena recibe instrucciones para crear nuevos recuerdos cuando sea necesario.

Combinación con otros servidores MCP

Al usar Serena a través de un cliente MCP, puede usarlo junto con otros servidores MCP. Sin embargo, tenga cuidado con las colisiones de nombres de herramientas. Consulte la información anterior.

Actualmente, existe una colisión con el popular servidor MCP del sistema de archivos. Dado que Serena también proporciona operaciones del sistema de archivos, probablemente no sea necesario habilitarlos simultáneamente.

Recomendaciones sobre el uso de Serena

Seguiremos recopilando las mejores prácticas a medida que la comunidad de Serena crece. A continuación, se presenta un breve resumen de lo que aprendimos al usar Serena internamente.

La mayoría de estas recomendaciones son válidas para cualquier agente de codificación, incluidos todos los agentes mencionados anteriormente.

¿Qué modelo elegir?

Para nuestra sorpresa, Serena pareció funcionar mejor con la versión no pensante de Claude 3.7 que con su versión pensante (aún no hemos hecho comparaciones exhaustivas con Gemini). La versión pensante tardaba más, presentaba más dificultades para usar las herramientas y, a menudo, simplemente escribía código sin leer suficiente contexto.

En nuestros experimentos iniciales, Gemini pareció funcionar muy bien. Lamentablemente, Gemini no es compatible con MCP (¿todavía?), por lo que la única forma de usarlo es mediante una clave API. Lo bueno es que Gemini es relativamente económico y admite contextos de gran longitud.

Incorporación

En la primera interacción, se le indica a Serena que realice la incorporación y escriba los primeros archivos de memoria. A veces (según el LLM), los archivos no se escriben en el disco. En ese caso, simplemente pídale a Serena que escriba las memorias.

En esta fase, Serena suele leer y escribir bastante texto, completando así el contexto. Recomendamos cambiar a otra conversación una vez realizada la incorporación para no quedarse sin tokens. La incorporación solo se realizará una vez, a menos que la active explícitamente.

Luego de la incorporación, te recomendamos que eches un vistazo rápido a las memorias y, si es necesario, las edites o agregues otras.

Antes de editar el código

Es mejor iniciar una tarea de generación de código desde un estado limpio de Git. Esto no solo facilitará la inspección de los cambios, sino que también permitirá que el propio modelo vea qué ha cambiado al llamar git diff y, por lo tanto, se corrija o continúe trabajando en una conversación de seguimiento si es necesario.

Importante : Dado que Serena escribirá en archivos usando los finales de línea nativos del sistema y podría querer ver la diferencia de Git, es importante establecer git config core.autocrlf en " true en Windows. Con git config core.autocrlf " en false en Windows, podrías obtener grandes diferencias debido únicamente a los finales de línea. Generalmente, es recomendable habilitar esta configuración de Git en Windows:

git config --global core.autocrlf true

Posibles problemas en la edición de código

En nuestra experiencia, los LLM son muy deficientes para contar, es decir, tienen problemas para insertar bloques de código en el lugar correcto. La mayoría de las operaciones de edición se pueden realizar a nivel simbólico, lo que permite solucionar este problema. Sin embargo, a veces, las inserciones a nivel de línea son útiles.

Se le indica a Serena que verifique dos veces los números de línea y cualquier bloque de código que editará, pero puede resultarle útil indicarle explícitamente cómo editar el código si surge algún problema.

Quedarse sin contexto

Para tareas largas y complejas, o en las que Serena ha leído mucho contenido, es posible que se alcance el límite de tokens de contexto. En ese caso, suele ser recomendable continuar en una nueva conversación. Serena cuenta con una herramienta dedicada a crear un resumen del estado actual del progreso y toda la información relevante para continuarlo. Puedes solicitar la creación de este resumen y guardarlo en una memoria. Después, en una nueva conversación, puedes pedirle a Serena que lea la memoria y continúe con la tarea. En nuestra experiencia, esto funcionó muy bien. La ventaja es que, al no tener que resumir en una sola sesión, Serena no suele perderse (a diferencia de otros agentes que resumen en segundo plano), y además se le indica que compruebe ocasionalmente si va por buen camino.

Además, a Serena se le indica que sea frugal con el contexto (por ejemplo, que no lea los cuerpos de los símbolos de código innecesariamente), pero descubrimos que Claude no siempre es muy bueno en ser frugal (Gemini parecía ser mejor en eso). Puedes indicarle explícitamente que no lea los cuerpos si sabes que no es necesario.

Control de ejecución de herramientas

Claude Desktop le preguntará antes de ejecutar una herramienta. Para la mayoría de las herramientas, puede simplemente hacer clic en "Permitir para este chat", especialmente si todos sus archivos están bajo control de versiones. Una excepción es la herramienta execute_shell_command ", donde podría querer inspeccionar cada llamada individualmente. Recomendamos revisar cada llamada a este comando y no habilitarlo para todo el chat.

Estructurando su base de código

Serena usa la estructura del código para buscar, leer y editar código. Esto significa que funcionará bien con código bien estructurado, pero podría fallar con código completamente desestructurado (como una clase-Dios con funciones enormes y no modulares). Las anotaciones de tipo también son muy útiles en este caso. Cuanto mejor sea tu código, mejor funcionará Serena. Por lo tanto, generalmente recomendamos escribir código bien estructurado, modular y tipado; no solo te ayudará a ti, sino también a tu IA.

Registro, análisis y pruebas

Serena no puede depurar (de momento, ningún asistente de programación puede hacerlo, según nuestro conocimiento). Esto significa que, para mejorar los resultados dentro de un bucle de agente , Serena necesita obtener información mediante la ejecución de pruebas, scripts, análisis de errores, etc. Suele ser muy útil incluir numerosos mensajes de registro con información explícita y contar con pruebas significativas. Estas últimas, en particular, suelen ayudar al agente a autocorregirse.

Generalmente recomendamos comenzar una tarea de edición desde un estado en el que se aprueben todas las pruebas y comprobaciones de pelusa.

Consejos generales

Descubrimos que suele ser buena idea dedicar tiempo a conceptualizar y planificar una tarea antes de implementarla, especialmente en tareas importantes. Esto ayuda a obtener mejores resultados y a aumentar la sensación de control y a mantenerse al tanto del proceso. Puedes crear un plan detallado en una sesión, donde Serena podría leer gran parte de tu código para crear el contexto, y luego continuar con la implementación en otra (posiblemente después de crear memorias adecuadas).

Solución de problemas

El soporte para servidores MCP en Claude Desktop y los diversos SDK de servidores MCP son desarrollos relativamente nuevos y pueden presentar inestabilidades.

La configuración de un servidor MCP puede variar según la plataforma y el cliente. Recomendamos usar siempre rutas absolutas, ya que las rutas relativas pueden ser fuente de errores. El servidor de idioma se ejecuta en un subproceso independiente y se llama con asyncio; a veces, un cliente puede provocar un bloqueo. Si la ventana de registro de Serena está activada y desaparece, sabrá qué ha ocurrido.

Es posible que algunos clientes (como Goose) no finalicen correctamente los servidores MCP. Busque procesos de Python colgados y finalícelos manualmente, si es necesario.

Registro de Serena

Para facilitar la resolución de problemas, hemos creado una pequeña utilidad de interfaz gráfica de usuario para el registro. Para la mayoría de los clientes, recomendamos habilitarla a través de la configuración del proyecto ( myproject.yml ) si surgen problemas. Muchos clientes también generan registros de MCP que pueden ayudar a identificar problemas.

Es posible que la interfaz gráfica de registro no funcione en todos los clientes ni en todos los sistemas. Actualmente, no funciona en macOS ni con extensiones de VSCode como Cline.

Expresiones de gratitud

Construimos Serena sobre múltiples tecnologías de código abierto existentes, siendo las más importantes:

multilspy . Un contenedor de excelente diseño para servidores de lenguaje siguiendo el LSP. No era fácil de extender con la lógica simbólica que Serena requería, así que, en lugar de incorporarlo como dependencia, copiamos el código fuente y lo adaptamos a nuestras necesidades.
SDK de Python MCP
Agno y el agente-ui asociado, que utilizamos para permitir que Serena trabaje con cualquier modelo, más allá de los que admiten el MCP.
Todos los servidores de idiomas que utilizamos a través de multilspy.

Sin estos proyectos, Serena no habría sido posible (o habría sido significativamente más difícil de construir).

Personalización de Serena

Es muy fácil ampliar la funcionalidad de IA de Serena con tus propias ideas. Simplemente implementa una nueva herramienta subclasificándola de serena.agent.Tool e implementa el método apply (no forma parte de la interfaz; consulta el comentario en Tool ). Por defecto, SerenaAgent tendrá acceso inmediato a ella.

También es relativamente sencillo añadir compatibilidad con un nuevo idioma . ¡Estamos deseando ver qué aporta la comunidad! Para más información sobre cómo contribuir, consulta aquí .

Lista completa de herramientas

Aquí está la lista completa de las herramientas de Serena con una breve descripción (salida de uv run serena-list-tools ):

activate_project : Activa un proyecto por nombre.
check_onboarding_performed : Comprueba si la incorporación ya se realizó.
create_text_file : crea/sobrescribe un archivo en el directorio del proyecto.
delete_lines : elimina un rango de líneas dentro de un archivo.
delete_memory : elimina una memoria del almacén de memoria específico del proyecto de Serena.
execute_shell_command : ejecuta un comando de shell.
find_referencing_code_snippets : busca fragmentos de código en los que se hace referencia al símbolo en la ubicación indicada.
find_referencing_symbols : busca símbolos que hacen referencia al símbolo en la ubicación dada (opcionalmente filtrado por tipo).
find_symbol : realiza una búsqueda global (o local) de símbolos con/que contengan un nombre/subcadena determinado (opcionalmente filtrado por tipo).
get_active_project : Obtiene el nombre del proyecto actualmente activo (si hay alguno) y enumera los proyectos existentes
get_symbols_overview : obtiene una descripción general de los símbolos de nivel superior definidos en un archivo o directorio determinado.
insert_after_symbol : inserta contenido después del final de la definición de un símbolo dado.
insert_at_line : inserta contenido en una línea determinada de un archivo.
insert_before_symbol : inserta contenido antes del comienzo de la definición de un símbolo dado.
list_dir : enumera archivos y directorios en el directorio dado (opcionalmente con recursión).
list_memories : enumera los recuerdos en el almacén de memoria específico del proyecto de Serena.
onboarding : realiza la onboarding (identificando la estructura del proyecto y las tareas esenciales, por ejemplo, para pruebas o construcción).
prepare_for_new_conversation : proporciona instrucciones para prepararse para una nueva conversación (para continuar con el contexto necesario).
read_file : lee un archivo dentro del directorio del proyecto.
read_memory : lee la memoria con el nombre dado desde el almacén de memoria específico del proyecto de Serena.
replace_lines : reemplaza un rango de líneas dentro de un archivo con contenido nuevo.
replace_symbol_body : reemplaza la definición completa de un símbolo.
restart_language_server : reinicia el servidor de idioma, puede ser necesario cuando se realizan ediciones que no se realizan a través de Serena.
search_for_pattern : realiza una búsqueda de un patrón en el proyecto.
summarize_changes : proporciona instrucciones para resumir los cambios realizados en el código base.
think_about_collected_information : Herramienta de pensamiento para reflexionar sobre la integridad de la información recopilada.
think_about_task_adherence : herramienta de pensamiento para determinar si el agente todavía está encaminado con la tarea actual.
think_about_whether_you_are_done : Herramienta de pensamiento para determinar si la tarea está realmente completada.
write_memory : escribe una memoria nombrada (para referencia futura) en el almacén de memoria específico del proyecto de Serena.