Serena

🚀 How to Use Serena

This guide provides a comprehensive introduction on how to install, initialize, and use Serena, a powerful tool for various project operations.

🚀 Quick Start

Installation and Initialization

1. Install Dependencies: Please follow the instructions in the INSTALL.md file to install Python, Node.js, and Yarn.
2. Create a Virtual Environment and Install Packages:

   python -m venv .venv && source .venv/bin/activate  # On macOS/Linux
   pip install -r requirements.txt
   

3. Initialize the Project:

   uv init your_project_name
   cd your_project_name
   

Start the Language Service

Run the following command in the project directory to start Serena's language service:

uv run serena

💻 Usage Examples

Project Activation and Management

1. Switch Projects:

   uv run serena activate <project_name>
   

2. Delete a Project:

   uv run serena delete-project <project_name>
   

File Operations

1. Create a File:

   uv run serena create-file <filename>
   

2. Read File Content:

   uv run serena read-file <filepath>
   

3. Delete a File:

   uv run serena delete-file <filepath>
   

Code Operations

1. Find a Symbol:

   uv run serena find-symbol <symbol_name>
   

2. Insert a Code Snippet:

   uv run serena insert-code <position> --content <code_content>
   

3. Replace a Code Segment:

   uv run serena replace-lines <start_line>:<end_line> --content <new_content>
   

Project Building and Testing

1. Run Tests:

   uv run serena run-tests
   

2. Build the Project:

   uv run serena build
   

🛠️ Custom Configuration

Create a New Tool

1. Create a new tool class file named new_tool.py and add the following content:

   class NewTool(Tool):
       def apply(self, context: Context) -> Context:
           # Implement the tool logic here
           return context
   

2. Register the New Tool:
   • Modify the serena/agent/tools/__init__.py file and add the following content:

     from .new_tool import NewTool
     
     __all__ = ['NewTool']
     

🚑 Troubleshooting

Problem Troubleshooting Steps

1. Check Logs: View the output logs of the language service for more information.
2. Restart the Service:

   uv run serena restart-language-server
   

3. Re - initialize the Project:

   uv init your_project_name
   

📚 Documentation

Complete Tool List

The following is a list of all Serena tools and their brief descriptions (obtained by running uv run serena-list-tools):

• activate_project: Activate a project with the specified name.
• check_onboarding_performed: Check if the initialization process has been completed.
• create_text_file: Create/overwrite a file in the project directory.
• delete_lines: Delete lines within a specified range in a file.
• delete_memory: Delete memory from Serena's project - specific storage.
• execute_shell_command: Execute a shell command.
• find_referencing_code_snippets: Find code snippets that reference a symbol at a given position.
• find_referencing_symbols: Find other symbols that reference a symbol at a given position (optional filtering by type).
• find_symbol: Search globally or locally in the project for symbols whose names contain the specified string.
• get_active_project: Get the name of the currently active project (if any) and list all projects.