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:

•ast-grep (if installed)
•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