serena

Serena - Semantic Code Understanding

IDE-like semantic code operations via CLI. Provides symbol-level code navigation, editing, and project memory.

Prerequisites

pip install serena-agent typer pyyaml

Quick Start

First-time setup: Launch the Web Dashboard to initialize and register the project:

python -m tools dashboard serve --open-browser

This will:

• Initialize Serena configuration
• Register the current project in ~/.serena/serena_config.yml
• Open the Web Dashboard for monitoring and configuration

Configuration: Edit .env file in skills/serena/ directory:

SERENA_CONTEXT=claude-code
SERENA_MODES=interactive,editing,onboarding
SERENA_PROJECT=.

Usage

Basic Command Structure

python -m tools [GLOBAL OPTIONS] <command> [COMMAND OPTIONS]

Global Options (must be specified before the command):

• -p, --project PATH - Project directory (default: current directory, env: SERENA_PROJECT)
• -c, --context TEXT - Execution context (auto-detected if not specified, env: SERENA_CONTEXT)
• -m, --mode TEXT - Operation modes (can be specified multiple times, env: SERENA_MODES)

Working with Different Projects

Important: When working with projects in different locations (especially cross-drive on Windows), use --project:

# Correct: Use --project for different project locations
python -m tools --project "/path/to/project" symbol find MyClass
python -m tools --project "E:\MyProject" file search "pattern"

# Incorrect: Don't use --path with absolute paths from different drives
python -m tools file search "pattern" --path "E:\MyProject"  # Will fail!

The --path option in subcommands expects relative paths within the project. Always use --project to set the project root first.

Common Operations

# Dashboard
python -m tools dashboard serve --open-browser
python -m tools dashboard info

# Symbol operations
python -m tools symbol find MyClass --body
python -m tools symbol overview src/main.py
python -m tools symbol refs MyClass/method
python -m tools symbol rename OldName NewName --path src/file.py

# Memory operations
python -m tools memory list
python -m tools memory read project_overview
python -m tools memory write api_notes --content "..."

# File operations
python -m tools file list --recursive
python -m tools file find "**/*.py"
python -m tools file search "TODO:.*" --path src

# Extended tools
python -m tools cmd run "git status"
python -m tools config read config.json