---
name: serena-setup
description: "Inspect, prepare or recover the independently installed Serena language tools. Use when Serena status is preparation-required, setup was interrupted, or the user asks to prepare, check or verify this plugin's dependencies."
---

# Serena setup

Use the installed package and its own host state. Do not reconstruct package
manager commands, install language servers manually, edit `global/code-tools.json`
in a checkout, or change the legacy harness registration.

## Resolve the installed package

Ask native Codex for the installed server declaration:

```powershell
$server = codex mcp get serena-plugin --json | ConvertFrom-Json
$root = $server.transport.env.PLUGIN_ROOT
$data = $server.transport.env.PLUGIN_DATA
```

If the server is absent, install `serena@coding-agents-harness` through native
Codex and retry. Keep `PLUGIN_ROOT` and `PLUGIN_DATA` in the process
environment for the setup wrapper:

```powershell
$env:PLUGIN_ROOT = $root
$env:PLUGIN_DATA = $data
& (Join-Path $root 'bin\serena-setup.cmd') status
```

`PLUGIN_DATA` is the stable writable state root across package updates. When
native Codex does not provide it, the wrapper and CLI fall back to
`CODEX_HOME/harness/serena-plugin`. Use one state root for status, preparation
and the MCP server; do not copy state into the versioned package cache.

## Operations

Read-only inspection:

```powershell
& (Join-Path $root 'bin\serena-setup.cmd') status
& (Join-Path $root 'bin\serena-setup.cmd') check
& (Join-Path $root 'bin\serena-setup.cmd') verify
```

Explicit preparation:

```powershell
& (Join-Path $root 'bin\serena-setup.cmd') prepare
```

Status and Check work before Python, Serena or language backends exist and do
not write state. A `preparation-required` result is expected on first use.
Preparation reuses compatible discovered packages or acquires the pinned
prerequisites into `PLUGIN_DATA`, then runs real Rust/Python semantic
acceptance. Report `ready` only when the report is `status: ready` with
`semantic.status: semantic-ready`; a preparation failure preserves the previous
registry and exposes its stage, cause and next action. Do not substitute a
manual package-manager sequence.

A successful preparation records plugin ownership and retires only an owned
legacy Serena registration after semantic verification. A `migration.status` of
`no-owned-legacy-serena` is normal on a fresh install; `serena-retired` means
the old owned connection was removed. Foreign or interrupted cutover state is
preserved and reported.

After preparation succeeds, start a new Codex session or refresh the MCP
catalogue. Do not claim the current session discovered tools before that
refresh is observed. The server entry launches `bin\serena-mcp.cmd`; it uses
the prepared registry in the same state root and never discovers, downloads or
installs packages at startup. After preparation it runs the immutable retained
generation outside the replaceable package cache. The server is not tied to the
thread's project, so call Serena's `activate_project` with the current project
root before navigation or edits.

Refreshing or replacing the marketplace source and rerunning native `plugin
add` selects a new package version without invalidating an open session. An
open session retains its generation; a new session uses the selected one.
Native `plugin remove` stops new discovery and removes the cache while keeping
`PLUGIN_DATA`, adopted packages, projects and retained generations as inactive
local state. Reinstall and start a new session to reuse them.

## Recovery

Run `status`, then `check`. Re-run `prepare` only for an explicit
preparation-required or interrupted-preparation state. If preparation fails,
keep the reported stage, cause and next action, and preserve the state root;
do not delete adopted packages, projects or the plugin cache. If the package
verification fails, reinstall the plugin from a producer-built marketplace
tree. If the prepared registry is missing, preparation was not completed;
restart Codex after a successful preparation. If an owned cutover was
interrupted, run the native code-tools Recover, then retry preparation.