Home
Login
oraios/serenaPlease refer to the latest official releases for information GitHub Homepage

Serena is a powerful coding agent toolkit that transforms large language models (LLMs) into a fully functional agent, working directly on your codebase.

MITPython 1.2koraios Last Updated: 2025-06-13

Serena Project Details

Project Overview

Serena is a powerful programming agent toolkit that transforms large language models (LLMs) into fully functional programming agents capable of working directly on your codebase. This project is developed by Oraios AI and open-sourced for the developer community.

Core Features

🚀 Core Capabilities

  • Semantic Code Retrieval and Editing: Provides IDE-like capabilities, extracting code entities at the symbol level and leveraging relational structures.
  • Fully Open Source and Free: Enhances the capabilities of your existing LLMs without additional costs.
  • Multiple Integration Methods: Supports MCP server, Agno framework, and custom agent framework integrations.

🔧 Technical Advantages

  • Based on Language Server Protocol (LSP): Offers a wide range of code query and editing functionalities through the widely implemented LSP.
  • Symbol-Level Understanding: Performs discovery and editing based on symbolic understanding of code, just like an experienced developer using an IDE.
  • Efficient and Precise: Efficiently finds the correct context and executes the correct operations, even in large and complex projects.

Supported Programming Languages

Directly Supported (Out-of-the-Box)

  • Python
  • Java (Note: Slower startup, especially noticeable on the first launch)
  • TypeScript

These languages are supported through the multilspy language server library used by Serena under the hood.

Integration Methods

1. Model Context Protocol (MCP)

Serena provides an MCP server that can be integrated with the following clients:

  • Claude Desktop
  • IDEs (e.g., VSCode, Cursor, IntelliJ)
  • Extensions (e.g., Cline, Roo Code)
  • Goose (provides a good CLI experience)
  • And many other clients, including the upcoming ChatGPT application support

2. Agno Framework

Through Agno (a model-agnostic agent framework), Serena can transform almost any LLM into a programming agent, supporting:

  • Paid API models from Google, OpenAI, and Anthropic
  • Free models from Ollama, Together, and Anyscale

3. Custom Agent Framework

Serena's tool implementations are decoupled from framework-specific code, making it easy to adapt to any agent framework.

Use Cases

Serena can be used for any programming task, including:

  • Code analysis
  • Project planning
  • Designing new components
  • Refactoring existing code
  • Complete autonomous programming tasks from initial analysis to implementation, testing, and finally, committing to a version control system.

Quick Start

Basic Installation

  1. Install uv (see official documentation for installation instructions)
  2. Clone the repository to /path/to/serena
  3. Copy serena_config.template.yml to serena_config.yml and adjust the settings
  4. Copy myproject.template.yml to myproject.yml and adjust project-specific settings
  5. To dynamically switch projects, add all project files to the projects list in serena_config.yml

Claude Desktop Integration

  1. Create a project configuration file myproject.yml
  2. Configure the MCP server in Claude Desktop:
    • Open File / Settings / Developer / MCP Servers / Edit Config
    • Add the following to claude_desktop_config.json:
    {
  "mcpServers": {
    "serena": {
      "command": "/abs/path/to/uv",
      "args": ["run", "--directory", "/abs/path/to/serena", "serena-mcp-server", "--project-file", "/abs/path/to/myproject.yml"]
    }
  }
}
  3. Save the configuration and restart Claude Desktop

Goose CLI Usage

  1. Install goose
  2. Use goose configure to add an extension
  3. Select "Command-line Extension" and name it "Serena"
  4. Add the command: /abs/path/to/uv run --directory /abs/path/to/serena serena-mcp-server /optional/abs/path/to/project.yml
  5. Disable the default developer extension

Agno GUI Usage

  1. Download the agent-ui code: npx create-agent-ui@latest
  2. Install Serena: uv pip install --all-extras -r pyproject.toml -e .
  3. Copy .env.example to .env and fill in the API key
  4. Start the Agno agent: uv run python scripts/agno_agent.py
  5. Start the UI: cd agent-ui && pnpm dev

Tools and Configuration

Main Tool Categories

  • Semantic Code Retrieval Tools: Find symbols, references, code snippets
  • Code Editing Tools: Insert, replace, delete code
  • File System Operations: Read, create, list files and directories
  • Shell Execution: Execute shell commands
  • Project Management: Activate projects, onboarding, memory management

Security Considerations

  • The use of all tools is generally recommended to provide maximum value.
  • The execute_shell_command tool allows arbitrary code execution and should be used with caution.
  • Specific commands can be disabled in the project configuration file.
  • Read-only mode is supported (read_only: true), allowing only analysis and suggestions without modifying the codebase.

Comparison with Other Programming Agents

Compared to Subscription-Based Agents (Windsurf, Cursor, VSCode)

Advantages:

  • No subscription fees
  • Not tied to a specific IDE
  • Not tied to a specific large language model or API
  • Uses language servers for symbol-level code understanding
  • Open source and small codebase, easy to extend and modify

Disadvantages:

  • Not directly integrated into the IDE, checking new code is not as seamless as built-in IDE tools

Compared to API-Based Agents (Claude Code, Cline, Aider)

Advantages:

  • Can be used as an MCP server, eliminating the need for API keys and avoiding API costs
  • This is a unique feature of Serena

Similarities:

  • Can all be used as API-based agents
  • All are powerful, with the main drawback being potentially high API costs

Compared to Other MCP Servers

  • To our knowledge, other programming-related MCP servers (such as DesktopCommander, codemcp) do not provide semantic code retrieval and editing tools.
  • They rely on purely text-based analysis.
  • Serena's integration of language servers and MCP features makes it unique and powerful for handling challenging programming tasks in large codebases.

Onboarding and Memory System

Onboarding

  • By default, Serena performs an onboarding process the first time it is launched for a project.
  • The goal is to familiarize Serena with the project and store memories for future interactions.

Memory System

  • Memory files are stored in .serena/memories/ in the project directory.
  • Agents can choose to read these files.
  • Users can read and adjust memory files as needed, or manually add new memory files.
  • The memory system significantly improves the user experience with Serena.

Usage Recommendations

Model Selection

  • The non-thinking version of Claude 3.7 seems to work better than the thinking version.
  • Gemini has performed well in preliminary experiments but does not yet support MCP.
  • Gemini is relatively inexpensive and can handle huge context lengths.

Best Practices

  1. Version Control: It is best to start code generation tasks from a clean git state.
  2. Windows Configuration: Set git config --global core.autocrlf true on Windows.
  3. Code Structure: Use well-structured, modular, and type-annotated code.
  4. Testing and Logging: Include detailed logging information and meaningful tests.
  5. Planning First: For complex tasks, conceptualize and plan first.
  6. Context Management: For long tasks, create summaries and continue in new conversations.

Complete Tool List

The following is a complete list of all Serena tools:

  • activate_project: Activates a project by name
  • check_onboarding_performed: Checks if onboarding has been performed
  • create_text_file: Creates/overwrites a file in the project directory
  • delete_lines: Deletes a range of lines in a file
  • delete_memory: Deletes a memory from Serena's project-specific memory store
  • execute_shell_command: Executes a shell command
  • find_referencing_code_snippets: Finds code snippets referencing a symbol at a given location
  • find_referencing_symbols: Finds symbols referencing a symbol at a given location
  • find_symbol: Performs a global (or local) symbol search
  • get_active_project: Gets the name of the currently active project
  • get_symbols_overview: Gets an overview of top-level symbols in a file or directory
  • insert_after_symbol: Inserts content after a symbol definition
  • insert_at_line: Inserts content at a given line in a file
  • insert_before_symbol: Inserts content before a symbol definition
  • list_dir: Lists files and directories in a directory
  • list_memories: Lists memories in the memory store
  • onboarding: Performs onboarding
  • prepare_for_new_conversation: Prepares for a new conversation
  • read_file: Reads a file in the project directory
  • read_memory: Reads a memory with the specified name
  • replace_lines: Replaces a range of lines in a file with new content
  • replace_symbol_body: Replaces the complete definition of a symbol
  • restart_language_server: Restarts the language server
  • search_for_pattern: Searches for a pattern in the project
  • summarize_changes: Provides a summary description of changes to the codebase
  • think_about_collected_information: A thinking tool for considering the completeness of collected information
  • think_about_task_adherence: A thinking tool for determining if the agent is still on the right track for the current task
  • think_about_whether_you_are_done: A thinking tool for determining if the task is truly complete
  • write_memory: Writes a named memory to the memory store for future reference

Summary

Serena is a powerful, fully open-source programming agent toolkit that provides developers with a free and robust AI programming assistant solution through semantic code understanding and multiple integration methods. Whether integrated with Claude Desktop via the MCP server or using various LLMs through the Agno framework, Serena can significantly improve programming efficiency and code quality.