Engine (`cmd/lsp_nav.rs`, on the pending outcomes of 20d1d28):
- `lsp.definition` (F12) and `lsp.references` (Shift+F12, sorted, with
line previews) return project-relative locations; locations outside
the project, such as PHAR stubs and symlink escapes, are dropped.
- `lsp.prepareRename` uses the word at the cursor when the server has
no prepareProvider.
- `lsp.rename` (F2) applies the workspace edit (`lsp_nav/edit.rs`):
1. Check everything first: inside the project, ranges fit (UTF-16,
CRLF), open buffers unchanged since the request, no file
operations, no incomplete edit.
2. Write closed files atomically through the VFS, restoring earlier
writes when a later one fails.
3. Change open buffers through `buffer.edit` (dirty, undoable).
4. Send each written file to Phpactor as didOpen/didSave/didClose
plus didChangeWatchedFiles; without this its index kept the old
names. Then the summary notification `notification.lsp.renamed`.
UI (`components/editor/nav/`):
- Mod+click goes to the definition, with a pointer cursor while Mod is
held.
- A location picker for several definitions (exclusive modal).
- A References tab in the bottom panel, grouped by file.
- An inline rename field with a use/file count (exclusive modal).
- `BufferSync.beginUndoableRemote` puts the engine's rename edit into
the editor history as one undo step per buffer.
- Catalog strings and tokens only.
Fake LSP server: `--script FILE` with scripted capabilities and
answers (additive next to M3.4's arms).
Tests:
- `crates/engine/tests/lsp_nav.rs` (fake): definition; bad positions;
references; prepareRename; a multi-file rename incl. a closed CRLF
file; refusals for outside the project, a bad range, a stale buffer,
bad names and no server.
- The ignored real-Phpactor test covers definition, references and a
rename and back across 3 files.
- Vitest `ui/tests/nav/`.
Live (Phpactor 2026.06.25.0, Windows, port 7935, tick on):
- definition 93 ms cold / 7-18 ms warm
- references ~140 ms
- prepareRename ~11 ms
- rename 28-59 ms
- index follows written files in 140 ms
- Phpactor 57 MB working set, ~1.6% of a core while ticking idle
Gate: 13 steps, 197 s, Vitest 484 + 1 skipped.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
5 KiB
Lutra
A fast, open-source, clean-room PHP IDE in the spirit of the PhpStorm workflow. Rust core, Vue interface, native on macOS, Windows and Linux.
Lutra is the Latin name of the otter. Sea otters are among the few animals that use tools: they crack shells open with a stone. Lutra is that stone for your PHP code.
Why Lutra
- Familiar. Project view, tool windows, Search Everywhere-style navigation, Go to Class, Find Usages, refactorings: the workflow PHP developers already know.
- Fast. A Rust core with an incremental index, search off the UI thread and a lightweight Tauri shell.
- Robust. No panics in shipped code, a crash-recovery journal for unsaved buffers, property-tested protocols.
- Open. MIT OR Apache-2.0, no account, no telemetry.
- Agent-native. Every action is a command that a JSON control channel and an MCP server expose, so Claude and other agents can work in the IDE the way a person does.
- PHP-first. Symfony, Laravel, Shopware and WordPress support are on the roadmap from the start.
Quick start
The foundation (M0) is built:
cargo xtask devopens an empty themed window andcargo xtask ciruns the quality gate. Thelutracommand below is the target of milestone M3.
git clone <repo-url> lutra
cd lutra
cargo xtask dev # desktop app in development mode
cargo xtask dev -- --control 7979 . # + JSON control channel
cargo xtask ci # fmt, clippy, tests, layers, assets, clean-room, frontend checks
The lutra command
Works today (M3.7): opening folders and files (at a line) in the running Lutra or starting it, and --wait. The rest arrives with M3 and later.
lutra . # open the current folder as a project
lutra src/Kernel.php:42 # open a file at a line
lutra diff a.php b.php # open the diff viewer
lutra --wait FILE # wait until the tab is closed (git config core.editor "lutra --wait")
lutra mcp # MCP server on stdio
lutra perf # check the performance budgets
Use it from Claude Code
claude mcp add lutra -- lutra mcp
Status
Pre-alpha (2026-10-17): M2 done. You can open a folder, browse it in the project tree with live updates from disk, and edit and save files in tabs with syntax highlighting for PHP (and HTML, CSS, JS/TS, JSON, YAML, Markdown), with every command in a palette (Mod+Shift+P) and settings and the light or dark theme in a settings dialog (Mod+,); unsaved text survives a crash and is offered back on the next open; M2 added find in files (Mod+Alt+F) and go to file, class or symbol (Mod+P, Mod+Alt+C, Mod+T); M3 has begun with an integrated terminal (Mod+Shift+T) and PHP language features from Phpactor: errors underlined as you type (Problems tab Mod+Alt+P), code completion, documentation on hover and parameter info, go to definition (F12 or Ctrl+click), find references (Shift+F12) and rename (F2). About 12 agent hours remain to the MVP (M3: language server, terminal, CLI and MCP). ROADMAP.md has the stage and what's next,
docs/target-app-parity.md the parity assessment and docs/gaps.md the ranked work list.
First target (MVP, M1–M3): open a project, project tree, tabs, editor with highlighting, find in files,
go to definition, completion and diagnostics via a language server, command palette, integrated terminal,
the lutra CLI, light and dark themes.
Agent and contributor rules (clean-room, asset policy, no panics, quality gates) are in AGENTS.md.
Every bundled asset is listed with its licence in ASSETS.md.
License
Lutra is dual-licensed under MIT or Apache-2.0, at your option. Copyright (c) 2026 Daniel Diekert and the Lutra contributors. Required notices are in NOTICE.
PhpStorm, IntelliJ IDEA and JetBrains are trademarks or registered trademarks of JetBrains s.r.o. Lutra is an independent, open-source project and is not affiliated with, sponsored by or endorsed by JetBrains s.r.o.; these names are used only to describe the workflows it is compatible with.