Serena

Instructions

Implementation Reference

• src/serena/tools/config_tools.py:5-19 (handler)

  The handler for the 'activate_project' tool. This Tool subclass defines the apply method executed when the tool is called. It delegates to the agent's activate_project_from_path_or_name method and appends an activation message.

  class ActivateProjectTool(Tool, ToolMarkerDoesNotRequireActiveProject):
      """
      Activates a project based on the project name or path.
      """
  
      def apply(self, project: str) -> str:
          """
          Activates the project with the given name or path.
  
          :param project: the name of a registered project to activate or a path to a project directory
          """
          active_project = self.agent.activate_project_from_path_or_name(project)
          result = active_project.get_activation_message()
          result += "\nIMPORTANT: If you have not yet read the 'Serena Instructions Manual', do it now before continuing!"
          return result

• src/serena/agent.py:569-586 (helper)

  Core helper method called by the tool handler to load a project from path or name (autogenerating if needed) and activate it by calling _activate_project.

  def activate_project_from_path_or_name(self, project_root_or_name: str) -> Project:
      """
      Activate a project from a path or a name.
      If the project was already registered, it will just be activated.
      If the argument is a path at which no Serena project previously existed, the project will be created beforehand.
      Raises ProjectNotFoundError if the project could neither be found nor created.
  
      :return: a tuple of the project instance and a Boolean indicating whether the project was newly
          created
      """
      project_instance: Project | None = self.load_project_from_path_or_name(project_root_or_name, autogenerate=True)
      if project_instance is None:
          raise ProjectNotFoundError(
              f"Project '{project_root_or_name}' not found: Not a valid project name or directory. "
              f"Existing project names: {self.serena_config.project_names}"
          )
      self._activate_project(project_instance)
      return project_instance

• src/serena/agent.py:535-551 (helper)

  Internal helper method that performs the actual project activation: sets the active project, updates active tools, schedules language server init if needed, and invokes activation callback.

  def _activate_project(self, project: Project) -> None:
      log.info(f"Activating {project.project_name} at {project.project_root}")
      self._active_project = project
      self._update_active_tools()
  
      def init_language_server_manager() -> None:
          # start the language server
          with LogTime("Language server initialization", logger=log):
              self.reset_language_server_manager()
  
      # initialize the language server in the background (if in language server mode)
      if self.is_using_language_server():
          self.issue_task(init_language_server_manager)
  
      if self._project_activation_callback is not None:
          self._project_activation_callback()

• src/serena/tools/tools_base.py:372-373 (registration)

  ToolRegistry automatically discovers and registers all Tool subclasses in the serena.tools package, including ActivateProjectTool, via iter_subclasses(Tool). This method provides the list used to instantiate tools.

  return list(t.tool_class for t in self._tool_dict.values())

• src/serena/tools/tools_base.py:180-180 (schema)

  The schema (JSON schema for MCP tool) is derived from the apply method's signature and docstring using func_metadata. This class method extracts the metadata statically.

  def get_apply_fn_metadata_from_cls(cls) -> FuncMetadata: