NEOVIM PLUGIN — LUA
Rose.nvim
OVERVIEW
Rose.nvim runs local Ollama chat and a bounded planner → coder → validation → reviewer workflow inside Neovim, and connects to Flow over MCP stdio with an optional private native Neovim socket for Flow's editor tools; cloud model APIs and Hugging Face transfers are separate, explicitly configured opt-ins, and native mode is the default.
HOW IT WORKS
- 1Install with `vim.pack`, lazy.nvim, or a native `pack/*/start` package — no build step or plugin dependencies in native mode — then call `require("rose").setup(opts)` with a workspace and model. Source: GitHub rose.nvim README.md, "Install".
- 2`:RoseAsk` chats with the configured local model with no tool execution; chat history is in memory only and bounded, in a scratch buffer that does not steal focus. Source: GitHub rose.nvim README.md, "Use".
- 3`:RoseAgent` runs sequential isolated planner/coder/reviewer contexts; only the coder receives `file_write`, defaults allow at most six coder model rounds, two each for planner and reviewer, and eight tool calls per response. Source: GitHub rose.nvim README.md, "Use".
- 4A host-owned validation gate decides success: each changed path needs an applicable named check returning `status="ok"` plus verified lint evidence, and the independent reviewer must return `{"approved":true,"issues":[],"summary":"..."}`; missing evidence stays unverified, with at most one bounded repair cycle by default. Source: GitHub rose.nvim README.md, "Verification means evidence, not model confidence".
- 5`:RoseFlow` lazily starts Flow (`flow serve`) and calls `flow_run` over newline JSON-RPC MCP stdio; Rose appends `--workspace`, conditional `--trusted`, and `--nvim <private socket>` when the bridge is available, and fails closed if a requested bridge is unavailable. Source: GitHub rose.nvim README.md, "Flow bridge".
- 6Optional subsystems stay off until configured: cloud providers (requires both `providers.enabled` and `providers.allow_cloud`), speech (`speech.enabled`), Hugging Face transfers (explicit manifest + preview approval), and the loopback Web UI (`webui.enabled` plus `:RoseWebUI`). Source: GitHub rose.nvim README.md.
CONCEPTS
CONFIGURATION
| Option | Default | What it does |
|---|---|---|
workspace | current working directory, resolved | Existing directory, resolved to an absolute realpath |
trusted | false | Allow configured workspace writes/checks/lint/debug and trusted Flow work; not an OS sandbox, not cloud consent |
legacy | false | `true` switches to the separate, unsupported historical implementation |
ollama.base_url | http://127.0.0.1:11434 | Local model endpoint; non-loopback requires `allow_remote` |
ollama.model | qwen2.5-coder:7b | Installed model ID; Rose does not install it |
ollama.timeout | 120000 (ms) | Request deadline, 1..3600000 ms |
ollama.allow_remote | false | Explicitly permit a non-loopback Ollama endpoint |
ollama.transport | auto | auto`/`curl` use the bounded safe curl adapter; `native` opts into `vim.net.request |
agent.max_iterations | 6 | Coder model rounds per cycle (1..30); planner/reviewer capped at `min(2, max_iterations)` |
agent.max_repair_rounds | 1 | Repair rounds after the initial cycle (0..3); `agent.max_cycles` derived default is 2 |
agent.max_tool_calls | 8 | Tool calls per model response (1..32) |
agent.max_context | 120000 (bytes) | Encoded message JSON bound; also bounds native chat history |
agent.max_tool_result | 24000 (bytes) | Encoded tool-result excerpt bound |
checks.<name>.cmd / kind / filetypes / timeout | cmd required; timeout adapter default 30000 ms | Explicit named checks (argv arrays, no shell); `kind` of `lint`/`typecheck`/`diagnostics` counts as static evidence |
flow.cmd | { "flow", "serve" } | External Flow process argv prefix |
flow.timeout | 600000 (ms) | Flow call deadline |
flow.bridge | true | Require the private native-editor bridge; failure stops rather than downgrades |
providers.enabled | false | Cloud adapter gate; must be exactly `true` for cloud calls |
providers.allow_cloud | false | Explicit consent for task/source/tool output to leave the device |
providers.provider | ollama | Chat provider selection (`ollama`/`openai`/`anthropic`/`xai`/`nvidia`/`perplexity`) |
speech.enabled | false | Master gate for dictation/read-aloud |
speech.record.max_seconds | 60 (seconds) | Recording duration bound, 1..600 s |
hub.python | python3 | Executable containing `huggingface_hub`; no automatic installation |
hub.max_workers | 4 | Concurrent Hub file workers, 1..16 |
hub.xet | auto | Use available Xet or explicit HTTP (`disabled`) |
scip.path | index.scip.json | Workspace-relative decoded SCIP JSON index (not raw protobuf) |
webui.enabled | false | Permit explicit `:RoseWebUI`; setup alone does not listen |
webui.host | 127.0.0.1 | Loopback host (`127.0.0.1`/`::1`/`localhost` only) |
webui.port | 0 | 0 chooses an ephemeral TCP port |
webui.max_clients | 8 | Simultaneous Web UI clients, 1..64 |
CONTROLS
| Action | Control |
|---|---|
| Chat with the configured model (no tools) | :RoseAsk [question] |
| Run the planner → coder → validation → reviewer agent | :RoseAgent [task] |
| Run a named check / all applicable checks | :RoseCheck [name] |
| Start Flow and run a task | :RoseFlow [task] |
| Cancel model/Hub requests; stop MCP, Flow socket, DAP probes | :RoseStop |
| Dictate / stop speech input | :RoseDictate` / `:RoseSpeechStop |
| Speak text or a range | :[range]RoseSpeak [text] |
| Speech provider status | :RoseSpeechStatus |
| Start / stop / inspect the Web UI | :RoseWebUI` / `:RoseWebUIStop` / `:RoseWebUIStatus |
| Hugging Face download / upload | :RoseHubDownload` / `:RoseHubUpload |
| Hub paper assets | :RoseHubPaper |
| Hub operation status / cancel | :RoseHubStatus` / `:RoseHubStop |
| Health report (no model contact) | :checkhealth rose |
| Hide chat buffer / ask from chat buffer / stop | `q` / `i` / `<C-c>` (in the scratch chat buffer) |
| Inspect resolved configuration | :lua vim.print(require("rose").options) |
| Shut down without reinitializing | require("rose").shutdown() |
NOT COVERED
- `docs/configuration.md` is the complete reference (34 KB as fetched); this pack lists the top-level, Ollama, agent, Flow, provider-gate, speech-gate, Hub and Web UI defaults, but not every nested provider/speech/debug/MCP field — e.g. per-provider `key_env` defaults (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `XAI_API_KEY`, `NVIDIA_API_KEY`, `PERPLEXITY_API_KEY`) and debug-probe tables exist in that file and were not all transcribed. - Primary target is Neovim 0.13 nightly (core tested on `v0.13.0-dev-1558+g8d5ebdf986`); behaviour on stable Neovim releases is not claimed in the README. - No default keybindings outside the chat buffer (`q`/`i`/`<C-c>`) are documented; all other controls are Ex commands.
REFERENCES
- Model Context Protocol specificationThe protocol of the :RoseFlow bridge: newline-delimited JSON-RPC over stdio between the plugin and the phlow server; this dated URL resolves to the currently published specification index.
- Neovim API documentation (:help api)The Nvim API reference — the buffer, window, and RPC surface the plugin's chat buffer, agent loop, and private editor socket are built on.