Skip to content

Latest commit

 

History

History
114 lines (87 loc) · 4.71 KB

CLAUDE.md

File metadata and controls

114 lines (87 loc) · 4.71 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Essential Commands (use these exact commands):

  • uv run poe format - Format code (BLACK + RUFF) - ONLY allowed formatting command
  • uv run poe type-check - Run mypy type checking - ONLY allowed type checking command
  • uv run poe test - Run tests with default markers (excludes java/rust by default)
  • uv run poe test -m "python or go" - Run specific language tests
  • uv run poe test -m vue - Run Vue tests
  • uv run poe lint - Check code style without fixing

Test Markers: Available pytest markers for selective testing:

  • python, go, java, rust, typescript, vue, php, perl, powershell, csharp, elixir, terraform, clojure, swift, bash, ruby, ruby_solargraph
  • snapshot - for symbolic editing operation tests

Project Management:

  • uv run serena-mcp-server - Start MCP server from project root
  • uv run index-project - Index project for faster tool performance

Always run format, type-check, and test before completing any task.

Architecture Overview

Serena is a dual-layer coding agent toolkit:

Core Components

1. SerenaAgent (src/serena/agent.py)

  • Central orchestrator managing projects, tools, and user interactions
  • Coordinates language servers, memory persistence, and MCP server interface
  • Manages tool registry and context/mode configurations

2. SolidLanguageServer (src/solidlsp/ls.py)

  • Unified wrapper around Language Server Protocol (LSP) implementations
  • Provides language-agnostic interface for symbol operations
  • Handles caching, error recovery, and multiple language server lifecycle

3. Tool System (src/serena/tools/)

  • file_tools.py - File system operations, search, regex replacements
  • symbol_tools.py - Language-aware symbol finding, navigation, editing
  • memory_tools.py - Project knowledge persistence and retrieval
  • config_tools.py - Project activation, mode switching
  • workflow_tools.py - Onboarding and meta-operations

4. Configuration System (src/serena/config/)

  • Contexts - Define tool sets for different environments (desktop-app, agent, ide-assistant)
  • Modes - Operational patterns (planning, editing, interactive, one-shot)
  • Projects - Per-project settings and language server configs

Language Support Architecture

Each supported language has:

  1. Language Server Implementation in src/solidlsp/language_servers/
  2. Runtime Dependencies - Automatic language server downloads when needed
  3. Test Repository in test/resources/repos/<language>/
  4. Test Suite in test/solidlsp/<language>/

Memory & Knowledge System

  • Markdown-based storage in .serena/memories/ directories
  • Project-specific knowledge persistence across sessions
  • Contextual retrieval based on relevance
  • Onboarding support for new projects

Development Patterns

Adding New Languages

  1. Create language server class in src/solidlsp/language_servers/
  2. Add to Language enum in src/solidlsp/ls_config.py
  3. Update factory method in src/solidlsp/ls.py
  4. Create test repository in test/resources/repos/<language>/
  5. Write test suite in test/solidlsp/<language>/
  6. Add pytest marker to pyproject.toml

Adding New Tools

  1. Inherit from Tool base class in src/serena/tools/tools_base.py
  2. Implement required methods and parameter validation
  3. Register in appropriate tool registry
  4. Add to context/mode configurations

Testing Strategy

  • Language-specific tests use pytest markers
  • Symbolic editing operations have snapshot tests
  • Integration tests in test_serena_agent.py
  • Test repositories provide realistic symbol structures

Configuration Hierarchy

Configuration is loaded from (in order of precedence):

  1. Command-line arguments to serena-mcp-server
  2. Project-specific .serena/project.yml
  3. User config ~/.serena/serena_config.yml
  4. Active modes and contexts

Key Implementation Notes

  • Symbol-based editing - Uses LSP for precise code manipulation
  • Caching strategy - Reduces language server overhead
  • Error recovery - Automatic language server restart on crashes
  • Multi-language support - 19 languages with LSP integration (including Vue)
  • MCP protocol - Exposes tools to AI agents via Model Context Protocol
  • Async operation - Non-blocking language server interactions

Working with the Codebase

  • Project uses Python 3.11 with uv for dependency management
  • Strict typing with mypy, formatted with black + ruff
  • Language servers run as separate processes with LSP communication
  • Memory system enables persistent project knowledge
  • Context/mode system allows workflow customization