Pi Serena Tools

Pi now gains IDE-like editing capabilities by bridging Serena’s semantic code tools into native Pi tools.

A Pi extension library that exposes the Serena MCP toolbox as native Pi tools via Streamable HTTP. It auto-starts a per-session Serena MCP server and provides a configurable tool blacklist.

Features

• IDE-like editing inside Pi via Serena’s semantic tooling
• Streamable HTTP transport for MCP calls
• Auto-started Serena MCP server scoped to the current project
• Per-instance port allocation (or override via SERENA_MCP_PORT)
• Tool blacklist with a UI menu (/serena-tool-blocker)
• Output truncation aligned with Pi defaults (50KB / 2000 lines)

Installation

As a Pi package

pi install npm:pi-serena-tools

Local development

pi -e /path/to/pi-serena-tools/index.ts

Configuration

Environment

• SERENA_MCP_PORT — Optional fixed port for the Serena MCP server (default: auto-select free port).

Project settings

Add to .pi/settings.json to persist the tool blacklist:

{
  "serena": {
    "blockedTools": ["read", "write", "edit", "ls", "find", "grep"]
  }
}

Command

Use /serena-tool-blocker to toggle blocked tools in a TUI menu.

Tools

The extension exposes Serena’s tool suite, including:

• Symbolic tools: find_symbol, find_referencing_symbols, get_symbols_overview, insert_after_symbol, insert_before_symbol, replace_symbol_body, rename_symbol, restart_language_server
• JetBrains tools: jet_brains_find_symbol, jet_brains_find_referencing_symbols, jet_brains_get_symbols_overview, jet_brains_type_hierarchy
• File tools: read_file, list_dir, find_file, create_text_file, replace_content, delete_lines, replace_lines, insert_at_line, search_for_pattern
• Workflow/config: activate_project, check_onboarding_performed, onboarding, get_current_config, switch_modes, open_dashboard, initial_instructions, prepare_for_new_conversation, summarize_changes, think_about_collected_information, think_about_task_adherence, think_about_whether_you_are_done
• Memory tools: read_memory, write_memory, list_memories, delete_memory, rename_memory, edit_memory
• Command tools: execute_shell_command

All tool signatures mirror the Serena repo definitions.

Usage Examples

find_symbol {
  "name_path_pattern": "MyClass/myMethod",
  "relative_path": "src",
  "include_body": false
}

read_file {
  "relative_path": "src/index.ts",
  "start_line": 0,
  "end_line": 200
}

replace_symbol_body {
  "name_path": "MyClass/myMethod",
  "relative_path": "src/my_class.ts",
  "body": "def myMethod(self):\n    pass"
}

Requirements

• uvx on PATH (the extension runs uvx --from git+https://github.com/oraios/serena serena ...).

Why this is great

With Serena wired in, Pi can edit code at the symbol level (classes, methods, functions) instead of raw text. That means safer refactors, accurate insertions, and IDE-like navigation directly from the terminal.

Notes

• The extension activates the current project (if the tool exists) on session start.
• The Serena MCP server is per Pi instance (no shared port unless SERENA_MCP_PORT is set).