Serena: The IDE for Coding Agents

To prevent 'agent drift' in VSCode (where the agent forgets Serena's instructions or fails to load tools), it is strongly recommended to set up reminder hooks. These hooks use remind to nudge the agent toward symbolic tools, activate to prompt project activation at session start, and cleanup to manage session data.

Create the file ~/.copilot/hooks/serena-hooks.json with the following content:

{
    "hooks": {
        "PreToolUse": [
            {
                "type": "command",
                "command": "serena-hooks remind --client=vscode"
            }
        ],
        "SessionStart": [
            {
                "type": "command",
                "command": "serena-hooks activate --client=vscode"
            }
        ],
        "Stop": [
            {
                "type": "command",
                "command": "serena-hooks cleanup --client=vscode"
            }
        ]
    }
}

To provide reliable code intelligence for C/C++ projects, Serena requires a compile_commands.json file at the repository root. This file must include proper C++ standard flags (e.g., -std=c++17) and all necessary include paths (-I flags) for cross-file reference finding.

Using clangd (Default)

Serena automatically downloads and manages clangd. Because clangd requires absolute paths, Serena will automatically detect relative paths in your compile_commands.json and transform them into absolute paths, writing a new file to .serena/compile_commands.json by default.

Using ccls

ccls requires manual installation and can be used if it performs better for your specific environment. Unlike clangd, ccls handles relative paths in compile_commands.json natively, so no transformed file is created.

Installation Commands:

Linux:

# Ubuntu/Debian (22.04+)
sudo apt install ccls

# Fedora/RHEL
sudo dnf install ccls

# Arch Linux
sudo pacman -S ccls

macOS:

brew install ccls

Windows:

choco install ccls

Serena provides native support for xAI's Grok Build CLI. Run: serena setup grok.

Manual Global Setup: grok mcp add --scope user serena -- serena start-mcp-server --context=grok --project-from-cwd

Manual Project-Level Setup: grok mcp add --scope project serena -- serena start-mcp-server --context=grok --project "$(pwd)"

Verification: Run grok inspect to verify Serena is listed.

Hooks: To enable hooks globally, create ~/.grok/hooks/serena-hooks.json. For a single project, use .grok/hooks/serena-hooks.json (requires /hooks-trust in Grok). Note that Grok ignores SessionStart stdout, so only PreToolUse and Stop are used:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "grep|read_file|run_terminal_command",
        "hooks": [
          {
            "type": "command",
            "command": "serena-hooks remind --client=grok",
            "timeout": 5
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "serena-hooks cleanup --client=grok",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

When deciding between using Serena's semantic tools and standard built-in text tools (like search_replace or open), follow these usage rules based on the task type:

Use Serena for:

• Move refactoring: Moving symbols or files while automatically updating imports (unique capability).
• Safe/Propagated deletion: Using safe_delete to prevent accidental breakage by checking for usages, or performing propagated deletes.
• Semantic navigation: Exploring type hierarchies, looking up external dependency symbols, or finding code references via find_referencing_symbols.
• Structural edits: Using insert_after_symbol or replace_symbol_body when you have a stable name path.
• Chained edits: When performing multiple edits in a single file, Serena's name-path addressing remains stable even as line numbers shift.

Use Built-in tools for:

• Small text edits: For 1-3 line changes, built-in search_replace is often more token-efficient.
• Non-code files: Reading or editing configs, docs, or notebooks.
• Free-text search: Searching for log strings, URLs, or magic constants using search_project.
• File/System operations: Creating new files, directory listing, or running terminal commands (e.g., git, pytest).

This is the preferred method as it emits clang-native commands, allowing clangd to resolve system and engine headers accurately using system-include paths.

Requirements:

• Install the "C++ Clang tools for Windows" component via the Visual Studio Installer (Modify > Individual Components).
• Ensure the project has been built at least once so *.generated.h headers exist.

Command: Run the following from your engine directory, replacing placeholders with your project details. The -OutputDir flag is mandatory to prevent the file from landing in the engine root.

<Engine>\Binaries\DotNET\UnrealBuildTool\UnrealBuildTool.exe -mode=GenerateClangDatabase -project="<YourProject>.uproject" <YourProject>Editor Win64 Development -OutputDir="<YourProject's directory>"

Note: You can add -NoExecCodeGenActions to the command to skip redundant code generation if you have already built the target.