pi-serena

Pi extension that registers Pi-native serena_* tools backed by a persistent TypeScript/Node worker. This avoids configuring Pi as an MCP client while still using Serena's semantic code APIs.

Note: Serena itself is a Python package. The TypeScript worker owns lifecycle, request/response handling, and Pi integration, and uses an embedded Python bridge subprocess only to call Serena internals because Serena does not provide a JavaScript SDK and its non-MCP project HTTP server is read-only.

Install

Install the published package from npm:

pi install npm:@bacnh85/pi-serena

From this repository checkout, install only this extension package:

pi install ./extensions/pi-serena

For local development from a checkout:

pi -e ./extensions/pi-serena

The package manifest points Pi directly at ./index.ts, so published npm installs and local installs load the same extension entrypoint.

There is intentionally no repository-level Pi package. Install each extension from its own subdirectory, matching extensions/pi-rtk and future extensions.

After install or update, restart Pi or run /reload in an existing Pi session.

Tools

• serena_status
• serena_list_tools
• serena_get_symbols_overview
• serena_find_symbol
• serena_find_referencing_symbols
• serena_replace_symbol_body
• serena_insert_before_symbol
• serena_insert_after_symbol
• serena_rename_symbol
• serena_safe_delete_symbol
• serena_search_for_pattern
• serena_replace_content
• serena_restart_language_server
• serena_get_current_config
• serena_check_onboarding_performed
• serena_onboarding
• serena_list_memories
• serena_read_memory
• serena_write_memory
• serena_delete_memory

All tool outputs are truncated to 50KB / 2000 lines to match Pi-friendly output limits. Most tools accept optional timeout_ms.

Commands

• /serena-status [project]
• /serena-dashboard [project]
• /serena-restart

The persistent Pi worker keeps one Serena bridge process per Pi process/session. It keeps the dashboard server available by default but does not open a browser tab automatically; use /serena-dashboard when you want to open it. Set SERENA_BRIDGE_WEB_DASHBOARD=0 to disable the dashboard server, or SERENA_BRIDGE_OPEN_DASHBOARD=1 to restore automatic browser launch. These variables are read from the process environment, current working directory .env.local/.env, or Pi global config .env.local/.env under $PI_CODING_AGENT_DIR, ~/.pi/agent, or compatibility path ~/.pi/agents.

Worker protocol

worker.ts implements the persistent worker client in TypeScript. The extension starts one worker per Pi process, lazily on first use, and shuts it down on session_shutdown.