lsp-simulate

Files (2)

• SKILL.md
• patterns.md · references/

SKILL.md (first lines)

> Requires the agent-lsp MCP server.

# lsp-simulate

Simulate code edits in memory before writing to disk. The LSP server applies
your changes to an in-memory overlay, runs diagnostics, and reports whether
the edit is safe — without touching any files.

## Prerequisites

LSP must be running for the target workspace. If not yet initialized, call
`start_lsp` before any simulation tool.

```
mcp__lsp__start_lsp(root_dir: "/your/workspace")
```

Auto-init note: agent-lsp supports workspace auto-inference from file paths.
Explicit `start_lsp` is only needed when switching workspace roots.

## Quick Start (single edit)

For a single what-if check, use `preview_edit` — it creates a session,
applies the edit, evaluates, and destroys the session in one call:

```
mcp__lsp__preview_edit(
  workspace_root: "/your/workspace",
  language: "go",
  file_path: "/abs/path/to/file.go",
  start_line: 42, start_column: 1,
  end_line: 42, end_column: 20,
  new_text: "replacement text"
)
```

Result:

```
{ net_delta: 0 }   -- safe to apply
{ net_delta: 2 }   -- 2 new errors introduced; do NOT apply
```

`net_delta: 0` means no new errors were introduced. Positive values mean
errors were introduced — inspect `errors_introduced` before deciding.

## Full Session Workflow (multiple edits)

Use a full session when applying several edits that build on each other, or
when you want to inspect the patch before deciding whether to write to disk.

**Step 1 — Create a simulation session**

```
mcp__lsp__create_simulation_session(
  workspace_root: "/your/workspace",
  language: "go"
)
→ { session_id: "abc123" }
```

**Step 2 — Apply edits in-memory**

Call `simulate_edit` one or more times. All edits are in-memory only.
Positions are 1-indexed (matching editor line numbers and `cat -n` output).

```
mcp__lsp__simulate_edit(
  session_id: "abc123",
  file_path: "/abs/path/to/file.go",
  start_line: 10, start_column: 1,
  end_line: 10, end_column: 30,
  new_text: "func NewClient(cfg Config) *Client {"
)
→ { session_id: "abc123", edit_applied: true, version_after: 1 }
```

Repeat for additional edits as needed.

**Step 3 — Evaluate the session**

```
mcp__lsp__evaluate_session(
  session_id: "abc123",
  scope: "file"
)
→ {
    net_delta: 0,
    confidence: "high",
    errors_introduced: [],
    errors_resolved: [],
    edit_risk_score: 0.0,
    affected_symbols: []
  }
```

`scope: "file"` (default) is faster and returns `confidence: "high"`.
`scope: "workspace"` catches cross-file type errors but returns
`confidence: "eventual"` (results may not be fully settled).

**Step 4 — Decision gate**

If `net_delta == 0`, proceed to commit. Otherwise, discard:

```
mcp__lsp__discard_session(session_id: "abc123")
```

**Step 5 — Commit the session**

```
-- Preview patch only (no disk write):
mcp__lsp__commit_session(session_id: "abc123", apply: false)

-- Write to disk:
mcp__lsp__commit_session(session_id: "abc123", apply: true)
```

**Step 6 — Destroy the session (always)**

From blackwell-systems/agent-lsp, MIT.

More from blackwell-systems/agent-lsp