# os-tk-serena

> Semantic code analysis via Serena MCP + LSP (optional, requires uv)

- Author: legout
- Repository: legout/os-tk-pi
- Version: 20260126202244
- Stars: 1
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/legout/os-tk-pi
- Web: https://mule.run/skillshub/@@legout/os-tk-pi~os-tk-serena:20260126202244

---

---
name: os-tk-serena
description: Semantic code analysis via Serena MCP + LSP (optional, requires uv)
optional: true
requires: uv, MCP server, pi-mcp-adapter
---

# os-tk-serena (optional skill)

## Purpose

Perform **symbol-level code analysis** and **semantic code operations** using Serena MCP server.

## When to Use

- Finding all references to a function/class/interface
- Understanding code structure via symbols
- Precise symbol-level edits (no line number guessing)
- Analyzing complex codebases with 20+ language support
- Refactoring with LSP rename support

## When NOT to Use

- **Simple text searches** – use `rg` instead (faster startup)
- **Grep-style keyword hunts** – `rg` is better suited
- **Projects without `uv`** – install uv first or use ast-grep fallback
- **Serena MCP server not running** – falls back to ast-grep

## Tools Provided

| Tool | Purpose |
|------|---------|
| `serena_find_symbol` | Locate symbols by name/path |
| `serena_find_referencing_symbols` | Find all usages/call sites |
| `serena_search_for_pattern` | Project-wide pattern search |
| `serena_get_symbols_overview` | File structure at symbol level |
| `serena_insert_after_symbol` | Add after symbol definition |
| `serena_insert_before_symbol` | Add before symbol definition |
| `serena_replace_symbol_body` | Replace full symbol implementation |

## Basic Usage

### Find a symbol
```bash
serena_find_symbol --name "UserService" --type class
```

### Find all references
```bash
serena_find_referencing_symbols --symbol-id "<symbol-id>"
```

### Get file structure
```bash
serena_get_symbols_overview --file src/auth.ts
```

### Symbol-aware edit
```bash
serena_insert_after_symbol --symbol-id "<symbol-id>" --content "..."
```

## Example: Finding All Callers of a Function

```bash
# Step 1: Find the function
serena_find_symbol --name "authenticate" --type method

# Returns: symbol-id: abc123

# Step 2: Find all references
serena_find_referencing_symbols --symbol-id "abc123"

# Returns: list of all call sites with file:line info
```

## Installation

```bash
# Install uv (required)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Serena MCP will be available via uvx
uvx --from git+https://github.com/oraios/serena serena start-mcp-server
```

## Integration with os-tk Workflow

- **os-tk-repo-scout**: Uses Serena for precise symbol search
- **os-tk-worker**: Uses Serena for symbol-aware edits
- **os-tk-reviewer-***: Uses Serena for thorough code analysis

## Fallback Behavior

If Serena MCP is unavailable, the tool selection system falls back to:

1. ast-grep (if installed)
2. ripgrep (always available)

## Configuration

In `.os-tk/config.json`:

```json
{
  "mcp": {
    "enabled": true,
    "servers": ["serena", "context7"]
  },
  "tools": {
    "searchHierarchy": ["serena", "ast-grep", "ripgrep"],
    "serena": {
      "enabled": true,
      "transport": "stdio"
    }
  }
}
```

## Language Support

Serena supports 20+ programming languages:

| Language | Notes |
|----------|-------|
| Python | ✓ Native support |
| TypeScript/JavaScript | ✓ Native support |
| Go | Requires gopls |
| Rust | Requires rustup |
| Java | Slow startup |
| C/C++ | Reference finding may have issues |
| Ruby | Uses ruby-lsp |
| And more... | Via LSP adapters |

## Known Limitations

- Requires MCP adapter (`~/.pi/agent/extensions/pi-mcp-adapter`)
- First run may be slow as LSP indexes the codebase
- Some languages (Java) have slower startup
- Requires uv to be installed

## Related Skills

- `os-tk-ast-grep`: Fallback for structural search
- `os-tk-repo-scout`: Uses Serena for code discovery
- `os-tk-worker`: Uses Serena for precise edits