Serena - Semantic Code Understanding
IDE-like semantic code operations via CLI. Provides symbol-level code navigation, editing, and project memory.
Execution Methods
# Prerequisites: pip install serena-agent typer
# Environment: SERENA_PROJECT (default: current directory)
# Symbol operations
python -m skills.serena.tools symbol find MyClass --body
python -m skills.serena.tools symbol overview src/main.py
python -m skills.serena.tools symbol refs MyClass/method
python -m skills.serena.tools symbol rename OldName NewName --path src/file.py
# Memory operations
python -m skills.serena.tools memory list
python -m skills.serena.tools memory read project_overview
python -m skills.serena.tools memory write api_notes --content "..."
# File operations
python -m skills.serena.tools file list --recursive
python -m skills.serena.tools file find "**/*.py"
python -m skills.serena.tools file search "TODO:.*" --path src
# Extended tools
python -m skills.serena.tools cmd run "git status"
python -m skills.serena.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
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
Phase 1: Exploration
symbol overview src/main.py # Understand file structure
symbol find MyClass --depth 1 # Explore class members
symbol find MyClass/method --body # Get implementation details
Phase 2: Analysis
symbol refs MyClass/method # Impact analysis
memory list # Check project knowledge
memory read architecture # Retrieve context
Phase 3: Modification
symbol find target --body # Verify target
symbol replace target --path f --body "..." # Edit
symbol rename old new --path f # Refactor
Error Handling
{"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 |
