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

Tool Routing Policy

Prefer Serena Over Built-in Tools

Task	Avoid	Use Serena CLI
Find function	grep "def func"	symbol find func --body
List file structure	cat file.py	symbol overview file.py
Find usages	grep "func("	symbol refs func
Edit function	Edit tool	symbol replace func --path file.py
Rename	Manual find/replace	symbol rename old new --path file.py

When to Use Built-in Tools

• Simple text search (non-code patterns)
• Configuration files (JSON, YAML)
• Documentation files (Markdown)

Command Reference

Dashboard Commands

Command	Description
dashboard serve [--open-browser] [--browser-cmd <path>]	Start Web Dashboard server
dashboard info	Show current configuration
dashboard tools	List active and available tools
dashboard modes	List active and available modes
dashboard contexts	List active and available contexts

Symbol Commands

Command	Description
symbol find <name> [--body] [--depth N] [--path file]	Find symbols by name
symbol overview <path>	List all symbols in file
symbol refs <name> [--path file]	Find symbol references
symbol replace <name> --path <file> --body <code>	Replace symbol body
symbol insert-after <name> --path <file> --content <code>	Insert after symbol
symbol insert-before <name> --path <file> --content <code>	Insert before symbol
symbol rename <name> <new> --path <file>	Rename symbol

Memory Commands

Command	Description
memory list	List all memories
memory read <name>	Read memory content
memory write <name> --content <text>	Create/update memory
memory edit <name> --content <text>	Edit memory
memory delete <name>	Delete memory

File Commands

Command	Description
file list [--path dir] [--recursive]	List directory
file find <pattern>	Find files by glob pattern
file search <pattern> [--path dir]	Search for regex pattern

Extended Commands

Command	Description
cmd run <command> [--cwd dir] [--timeout N]	Execute shell command
cmd script <path> [--args "..."]	Execute script file
config read <path> [--format json|yaml]	Read config file
config update <path> <key> <value>	Update config value

Workflow Commands

Command	Description
workflow onboarding	Run project onboarding
workflow check	Check onboarding status
workflow tools [--scope all]	List available tools

Workflow Examples

Phase 1: Exploration

python -m tools symbol overview src/main.py           # Understand file structure
python -m tools symbol find MyClass --depth 1         # Explore class members
python -m tools symbol find MyClass/method --body     # Get implementation details

Phase 2: Analysis

python -m tools symbol refs MyClass/method            # Impact analysis
python -m tools memory list                           # Check project knowledge
python -m tools memory read architecture              # Retrieve context

Phase 3: Modification

python -m tools symbol find target --body             # Verify target
python -m tools symbol replace target --path f --body "..."  # Edit
python -m tools symbol rename old new --path f        # Refactor

Error Handling

All CLI output is JSON:

// Success
{"result": <data>}

// Error
{"error": {"code": "ERROR_CODE", "message": "description"}}

Error Code	Recovery
INVALID_ARGS	Check --help
TOOL_NOT_FOUND	Use workflow tools
INIT_FAILED	Check serena-agent installation
RUNTIME_ERROR	Check error message

Anti-Patterns

Prohibited	Correct
Read entire file to find function	symbol find func --body
Grep for function calls	symbol refs func
Manual search-replace rename	symbol rename old new --path f
Skip impact analysis	symbol refs before editing