dsh-serena

Readme

# dsh-serena

[![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/akash-digitavision/dsh-serena)

**One-line value:** install this and every DeepSeek Harness agent gains IDE-grade symbolic code intelligence — `find_symbol`, `find_referencing_symbols`, `rename_symbol`, `replace_symbol_body`, `get_symbols_overview` and more — via the [Serena](https://github.com/oraios/serena) MCP server, plus session hooks that keep agents actually using it.

**Capability category:** 工具与能力 (Tools & Capabilities)
**License:** MIT · **Compatibility:** DSH ≥ 0.2.0-rc.2 (bundles API); Windows/macOS/Linux; Python ≥ 3.11 for the Serena CLI

## What it adds to every agent on the profile

| Row | Module | Purpose |
|---|---|---|
| `mcp-serena` | `@deepseek-ai/dsh-mcp-client` | Spawns the Serena MCP server (stdio) → `mcp__serena__*` tools: symbol search & overview, find references/implementations/declarations, rename & safe-delete symbols, symbolic editing, per-project memories, diagnostics |
| `dsh-hooks-claude-code` | `@deepseek-ai/dsh-hooks-claude-code` (dependency of this bundle) | Runs `~/.dsh/hooks.json`: session-start project activation prompt, tool-drift reminders toward Serena's tools, stop cleanup |

Launched with `--context claude-code --project-from-cwd`: each session auto-activates its workspace as the Serena project, and tools that duplicate DSH built-ins (file read/search/shell) stay hidden.

## Install

**One command (recommended):**

```bash
dsh plugin --profile web add github:akash-digitavision/dsh-serena
```

or in **Settings → Plugin Market** (DSH Plugin Hub), search for `dsh-serena`.

### Prerequisites

1. **The Serena CLI** — the official install puts `serena` on your PATH (the bundle's default):
   ```bash
   # install uv first: https://docs.astral.sh/uv/getting-started/installation/
   uv tool install -p 3.13 serena-agent
   ```
   Custom location? Point the bundle at it:
   ```powershell
   setx SERENA_COMMAND "C:\path\to\serena.exe"
   ```
   > **Windows note (Smart App Control / WDAC):** application-control policies may block uv-managed unsigned Python builds. Workaround: build a venv from a trusted/signed interpreter, `pip install serena-agent` into it, and `setx SERENA_COMMAND` to that venv's `serena.exe`.
2. **The hooks file** `~/.dsh/hooks.json` (Windows: `%USERPROFILE%\.dsh\hooks.json`) — copy [`hooks.template.json`](./hooks.template.json):
   ```json
   {
     "SessionStart": [{ "matcher": "", "hooks": [{ "type": "command", "command": "serena-hooks activate --client=claude-code" }] }],
     "PreToolUse":    [{ "matcher": "", "hooks": [{ "type": "command", "command": "serena-hooks remind --client=claude-code" }] }],
     "Stop":          [{ "matcher": "", "hooks": [{ "type": "command", "command": "serena-hooks cleanup --client=claude-code" }] }]
   }
   ```
   `serena-hooks` ships with `uv tool install serena-agent`. If it is not on the DSH process PATH, use the absolute path to the executable in the template.

Then **restart DeepSeek Harness**. Verify by asking an agent: *"activate this project with serena"*.

## Permissions & external services

- Spawns a local `serena` MCP server process (language servers may download per-language tooling on demand)
- Reads/writes only your activated project workspaces; memories stored per-project in `.serena/`
- No accounts, no API keys, no telemetry

## Known limitations

- The hooks-bridge dependency is version-pinned (`@deepseek-ai/dsh-hooks-claude-code` `0.2.0-rc.2`); if your DSH runtime is newer and install is rejected for peer incompatibility, match the version to your runtime
- First symbol query in a new project downloads that language's language server — first call can be slow

## Uninstall

Remove `dsh-serena` from the profile `dsh.profile.bundles` + `dependencies` (or `dsh plugin remove`), then restart the host. The Serena CLI, venv and hooks file are independent of the bundle.

## Credits

Upstream: [oraios/serena](https://github.com/oraios/serena) (MIT / GPL-3.0) — this bundle only wires it into DeepSeek Harness.