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 |
