Dianel555/DSkills / skills/serena
serena
VerifiedSemantic code understanding with IDE-like symbol operations. Use when: (1) Large codebase analysis (>50 files), (2) Symbol-level operations (find, rename, refactor), (3) Cross-file reference tracking, (4) Project memory and session persistence, (5) Multi-language semantic navigation. Triggers: "find symbol", "rename function", "find references", "symbol overview", "project memory". IMPORTANT: Prioritize Serena's symbolic tools over file-based grep/read for code exploration.
| File | Kind | Size |
|---|---|---|
| .env.example | other | 619 B |
| README.md | markdown | 6.8 KB |
| SKILL.md | skill md | 7.1 KB |
| tools/__init__.py | script | 310 B |
| tools/__main__.py | script | 94 B |
| tools/cli/__init__.py | script | 3.4 KB |
| tools/cli/cmd.py | script | 1.0 KB |
| tools/cli/config.py | script | 1.1 KB |
| tools/cli/dashboard.py | script | 5.3 KB |
| tools/cli/file.py | script | 1.4 KB |
| tools/cli/memory.py | script | 1.5 KB |
| tools/cli/symbol.py | script | 3.7 KB |
| tools/cli/workflow.py | script | 780 B |
| tools/core.py | script | 7.8 KB |
| tools/extended/__init__.py | script | 30 B |
| tools/extended/cmd_tools.py | script | 3.7 KB |
| tools/extended/config_tools.py | script | 4.9 KB |
| tools/output.py | script | 402 B |
| tools/paths.py | script | 1.5 KB |
| tools/server/__init__.py | script | 110 B |
| tools/server/dashboard_server.py | script | 14.1 KB |
| tools/tests/__init__.py | script | 30 B |
| tools/tests/conftest.py | script | 256 B |
| tools/tests/test_cli_dashboard.py | script | 3.0 KB |
| tools/tests/test_cli_file.py | script | 3.4 KB |
| tools/tests/test_cli_memory.py | script | 2.6 KB |
| tools/tests/test_core.py | script | 5.4 KB |
| tools/tests/test_module_path.py | script | 3.0 KB |
| tools/tests/test_paths.py | script | 2.8 KB |
README.md
View on GitHub# Serena CLI
Semantic code understanding with IDE-like symbol operations and Web Dashboard. MCP-independent CLI for code navigation, editing, and project memory.
## Features
- **Web Dashboard**: Real-time configuration monitoring and management
- **Symbol Operations**: Find, rename, replace, insert symbols with language-aware precision
- **Cross-file References**: Track symbol usages across entire codebase
- **Project Memory**: Persist and retrieve project knowledge across sessions
- **Extended Tools**: Shell commands, config file operations
- **Cross-Drive Support**: Work with projects on any drive (Windows) or path (Unix)
- **Auto Project Registration**: Automatically registers projects in global Serena config
## Installation
```bash
pip install serena-agent typer pyyaml
```
## Quick Start
**First-time setup**: Launch the Web Dashboard to initialize and register the project:
```bash
# Start Web Dashboard (recommended for first-time use)
python -m tools dashboard serve --open-browser
# Or manually open browser after starting
python -m tools dashboard serve
# Then open: http://127.0.0.1:24282/dashboard/index.html
```
**Configuration**: Create `.env` file in `skills/serena/` directory:
```bash
SERENA_CONTEXT=claude-code
SERENA_MODES=interactive,editing,onboarding
SERENA_PROJECT=.
SERENA_DASHBOARD_ENABLED=true
SERENA_DASHBOARD_PORT=24282
```
**Basic Usage**:
```bash
# Find a symbol
python -m tools symbol find MyClass --body
# List symbols in file
python -m tools symbol overview src/main.py
# Find references
python -m tools symbol refs MyClass/method
# List available tools
python -m tools workflow tools
```
## Command Structure
```bash
python -m tools [GLOBAL OPTIONS] <command> [COMMAND OPTIONS]
```
### Global 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`:
```bash
# Correct: Specify project path with --project
python -m tools --project "E:\MyProject" file search "pattern"
python -m tools --project "/home/user/project" symbol find MyClass
python -m tools --project "D:\workspace\app" symbol refs MyClass
# Incorrect: Don't use --path with absolute paths from different drives
python -m tools file search "pattern" --path "E:\MyProject" # Will fail!
```
**Why?** The `--path` option in subcommands expects **relative paths** within the project. Always use `--project` to set the project root first.
## CLI Commands
### Dashboard Commands
| Command | Description |
|---------|-------------|
| `dashboard serve [--open-browser] [--browser-cmd <path>]` | Start Web Dashboard server |
| `dashboard info` | Show current configuration overview |
| `dashboard tools` | List active and available tools |
| `dashboard modes` | List active and available modes |
| `dashboard contexts` | List active and available contexts |
**Dashboard Options**:
- `--open-browser` / `--no-open-browser`: Auto-open browser (default: False)
- `--browser-cmd <path>`: Specify browser executable path
- `--host <address>`: Listen address (default: 127.0.0.1)
- `--port <number>`: Listen port (default: 24282, 0 for auto-select)
- `SERENA_BROWSER_CMD`: Environment variable for browser command
### Symbol Operations
| 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 Operations
| 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 Operations
| Command | Description |
|---------|-------------|
| `file list [--path <dir>] [--recursive]` | List directory contents |
| `file find <pattern>` | Find files by glob pattern |
| `file search <pattern> [--path <dir>]` | Search for regex pattern in files |
### Extended Tools
| Command | Description |
|---------|-------------|
| `cmd run <cmd> [--cwd <dir>] [--timeout <N>]` | Execute shell command |
| `cmd script <path> [--args "..."]` | Execute script file |
| `config read <path> [--format json\|yaml]` | Read JSON/YAML config |
| `config update <path> <key> <value>` | Update config value |
### Workflow
| Command | Description |
|---------|-------------|
| `workflow onboarding` | Run project onboarding |
| `workflow check` | Check onboarding status |
| `workflow tools [--scope all]` | List available tools |
## Output Format
All CLI output is JSON:
```json
// Success
{"result": <data>}
// Error
{"error": {"code": "ERROR_CODE", "message": "description"}}
```
**Error codes**: `INVALID_ARGS`, `TOOL_NOT_FOUND`, `INIT_FAILED`, `RUNTIME_ERROR`
## Web Dashboard Features
The Web Dashboard provides:
- **Real-time Configuration**: View active context, modes, and tools
- **Project Management**: See registered projects and active project
- **Tool Monitoring**: Track active and available tools
- **Configuration Editing**: Edit `.env` file directly from browser
- **Auto Registration**: Automatically adds project to `~/.serena/serena_config.yml`
Access the dashboard at: `http://127.0.0.1:24282/dashboard/index.html`
## Project Structure
```
skills/serena/
├── SKILL.md
├── README.md
├── .env.example
└── tools/
├── core.py # SerenaCore wrapper
├── paths.py # Path utilities
├── output.py # JSON output utilities
├── cli/ # Typer CLI commands
│ ├── dashboard.py
│ ├── symbol.py
│ ├── memory.py
│ ├── file.py
│ ├── workflow.py
│ ├── cmd.py
│ └── config.py
├── server/ # Web Dashboard server
│ └── dashboard_server.py # Flask HTTP server
└── extended/ # Extended tools
├── cmd_tools.py
└── config_tools.py
```
## License
MIT
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |