DeepWorkPlan Vim
DeepWorkPlan Vim is the terminal editor for Deep Work Plan: a Neovim configuration for people, and for coding agents, that work in a terminal. Your plans, your documentation and an index of every command are one keystroke away.
It is a separate product, offered as the optional vim addon of Deep Work Plan v7 (pack v7.9.0). Deep Work Plan works with any editor or none, and the editor does not require Deep Work Plan: you add it to a machine on its own, and it works as an editor whether or not a plan exists. This page describes release v1.0.1, a maintenance release of the first stable release, v1.0.0: from v1.0.0 on, the installer and its flags (with the matching DWP_VIM_* variables), the addon surface (addon/surface.json, interface 1), the editor commands :DwpPlans, :DwpLanes, :DwpCommands and :DwpConfig, the dwpvim.json keys and the keybindings pinned by the mapping contract change incompatibly only in a new major version.
Why a terminal editor for Deep Work Plan
A Deep Work Plan is a folder of Markdown under .dwp/plans/: a goal, atomic tasks, validation gates and a running log. People review it, agents execute it, and both often do it from a terminal. An editor built for that work keeps three things close: the plan itself, the documentation around it, and the keystrokes that move you between them.
DeepWorkPlan Vim is that editor. The aim is a mini VS Code in the terminal: navigate files, see which files changed, review the diff and approve or discard changes, friendly and lightweight, agent-first, with the plan status always in view. It is a curated Neovim configuration — language servers, completion, formatting, fuzzy finding, a file tree and curated color themes, loaded lazily — plus the few surfaces that make it the editor for Deep Work Plan.
- Plan
- Tasks
- Gates
- Done
The tour: a command index that cannot drift
Press SPC h h (Space is the leader key), or run :DwpCommands, and the editor lists every mapping it has with a one-line description. The list is generated from the live keymaps, so a mapping defined anywhere shows up in the index without being registered, and the index cannot fall out of date.
That is the whole tour: launch nvim, then press Space, h, h.
- SPC h h Open this command index
- SPC P Plan browser
- SPC m p Preview Markdown in the browser
- SPC m r Render Markdown in the buffer
- <C-a> Select the whole file
- SPC y Copy to the system clipboard
- SPC t f Find files
- SPC t t Live search in the project
- SPC x Run or preview the current file
- SPC n File tree
- SPC t h Pick a color theme
- and every other mapping, always current
What you get
Five features, each one keystroke away.
| Feature | Keys | What it does |
|---|---|---|
| Generated command index | SPC h h |
Every mapping in the configuration, generated from the live keymaps. |
| VS Code-shaped gestures | <C-a>, SPC y |
Select the whole file in one key, and copy to the system clipboard. Plain y also lands there, because the clipboard is system-wide; where no clipboard tool exists (a container, an SSH session) the copy travels through OSC 52. |
| Deep Work Plan browser | SPC P |
A sidebar over the plans in your repository, grouped by status with progress bars; click a plan to open its reader. |
| Markdown viewer | SPC m p, SPC m r |
Preview Markdown in the browser, or render it in the buffer. |
| Verified installer | — | A self-contained installer for macOS, Linux and WSL, with a documented manual path for Windows. |
Plans without leaving the editor
SPC P, :DwpPlans, or a click on the statusline segment opens the plans sidebar. It covers every .dwp/plans/ folder under the current directory and your Neovim config directory, and groups plans most-attention-first: Working, Needs attention, Ready, Not started, Done. Each plan shows a progress bar.
Click a plan, or press Enter on it, to open the reader: the goal in one sentence, the status and progress, the task checklist with the current task marked, and plain-language jumps into the plan’s own files. The statusline shows the live active plan, and the start screen lists the top three. These surfaces explain plans; they never write under .dwp/.
The sidebar answers the mouse and the keyboard. The small arrow beside a plan shows or hides its tasks and files, and a click on a task or file opens it. j, k, the arrow keys, Ctrl-n and Ctrl-p jump from plan to plan, skipping blank rows and decoration. Each section shows its count, status colors mark the icon and the progress bar, live plans have strong titles and settled plans dim ones, and a Done group of more than six plans opens collapsed. The window is read-only and quiet: editing keys do nothing instead of printing an error.
Plans and the file tree take turns: opening one sidebar closes the other, so you look at one thing at a time. The reader closes together with the plans sidebar. Whether opening one sidebar closes the other is the sidebars.exclusive key in dwpvim.json.
An orchestrator plan — a lead coordinating lanes in other repositories — also gets a read-only lanes view: :DwpLanes, or L in the plans sidebar. It reads the plan’s lane tables and shows each lane’s live state from herdr-peers lanes; with no Herdr reachable, it says so and shows the tables alone. See Running many agents.
To read a plan’s Markdown files in place, SPC m p previews the current buffer in the browser and SPC m r renders it inside the buffer. Both work in Markdown buffers only.
The dashboard
The start screen is DeepWorkPlan Vim’s own. It shows the Deep Work Plan logo engraved in braille characters with a tiny VIM tucked under its P, a “powered by Dailybot” credit beneath, and an engraved scene on the right: the Deep Work Plan lighthouse and a ship sailing in its sea. The beam pulses slowly while the dashboard is on screen; set vim.g.dwp_greeter_pulse = false to turn that off.
The scene comes in six heights, chosen by the rows the window leaves free. In a narrower window the wordmark stacks over the scene or stands alone. Wide windows show the shortcuts and “Your plans” side by side, and narrow ones stack them. Press Enter to activate the row under the cursor; SPC P opens the plans sidebar.
Configure the sidebars
A dwpvim.json file sets where the two sidebars sit and how wide they are. The file in the editor’s directory (~/.config/nvim) applies to every project, and a .dwpvim.json in the directory where you start Neovim overrides it for that project. Settings are read at startup, so restart Neovim after editing a file.
{
"tree": { "side": "left", "width": 40 },
"plans": { "side": "left", "width": 48 },
"sidebars": { "exclusive": true }
}
| Key | Values | Default | What it does |
|---|---|---|---|
tree.side |
"left" or "right" |
"left" |
Side of the file tree (SPC n) |
tree.width |
whole number, 20 to 120 | 40 |
Maximum width of the tree; it still shrinks to its content |
plans.side |
"left" or "right" |
"left" |
Side of the plans sidebar (SPC P) |
plans.width |
whole number, 20 to 120 | 48 |
Maximum width of the plans sidebar |
sidebars.exclusive |
true or false |
true |
One sidebar at a time; false lets both stay open |
A missing file is fine. A file that is not valid JSON, an unknown key or an invalid value is ignored and reported, never fatal. Run :DwpConfig to see every value in effect, the file it came from and any problem found.
A lighter editor
Version 0.6.0 removes what nobody used, so there are fewer plugins to pin and fewer packages to install and update at first start:
- Eleven Mason language servers are retired: efm, diagnosticls, tailwindcss, grammarly, bashls, and the servers for astro, svelte, Vue 2, Angular, SQL and Vim script.
- nvim-lint is removed, because no linter was ever configured.
- The prettier formatter entries are removed, because nothing installed prettier.
:Formatkeeps biome, black, shfmt and stylua. - marksman stays for following links, completing links and headings, and the outline, with its diagnostics silenced. Markdown stays without a formatter on purpose.
Only the servers the configuration lists are enabled, even when Mason still holds others from an earlier setup. Every plugin, server and tool, with the reason it is there, is listed in PLUGINS.md.
Install
The install is three commands: download the script, check it against the SHA-256 of the file this site serves, then run it. The installer pins its own release, so it installs exactly v1.0.1, the release this page describes, unless you choose another version.
curl -fsSL -o install.sh https://deepworkplan.com/vim/install.sh && \
echo "24a550239108a71434e993675389c27c64d88c4c07af8efc9be98d23897fb716 install.sh" | shasum -a 256 -c && \
bash install.sh Inspect before you run
Prefer to read it first? Download the script, check its fingerprint, read it, then run it.
- Download the script
curl -fsSL https://deepworkplan.com/vim/install.sh -o install.sh - Print its SHA-256 and compare it with the value below
sha256sum install.sh - Read the script
less install.sh - Run the script
bash install.sh
- SHA-256 of the script served now
24a550239108a71434e993675389c27c64d88c4c07af8efc9be98d23897fb716- 46504 bytes · 1109 lines
On macOS, use shasum -a 256 install.sh for the second step.
To choose a release, pass --version or set DWP_VIM_VERSION: an exact version, a '>=' floor or latest. DWP_VIM_REF takes a branch or a commit. Older releases may not include every feature described on this page.
On Windows these commands do not apply; the repository README documents the manual path. Windows install path
In order, the installer:
- Checks your OS and package manager, and installs git, curl and a Lua interpreter if any are missing (none with
--skip-packages). - Resolves the version: its own release, or the one
--versionasks for. - With
--nvim X.Y.Z, installs that Neovim release into~/.local/opt, verified against the SHA-256 that Neovim publishes. - Asks before touching an existing Neovim configuration. Without a terminal, it stops and changes nothing, unless
--yestells it to move that configuration aside. - Clones the repository into
~/.config/nvim, or updates it when it is already there. - Runs the repository’s own
lua install.lua. - Installs the plugins headlessly and checks them, so there is no quit-and-reopen step. With
--strict, a failed or incomplete plugin install is an error.
The script served here is a byte-identical copy of install.sh at the v1.0.1 tag. Its checksum is served next to it, at https://deepworkplan.com/vim/install.sh.sha256, so you can verify the download with shasum -a 256 -c install.sh.sha256 (on Linux, sha256sum -c install.sh.sha256). For a check from a second origin, compare it with the install.sh line of SHA256SUMS on the GitHub release. Run bash install.sh --help to list every option.
Choose a version
By default the installer installs its own release, v1.0.1. To choose another, set DWP_VIM_VERSION or pass --version: both do the same thing, so use whichever reads better, and a flag wins over the environment. Each accepts:
| Form | Example | Installs |
|---|---|---|
| Exact version | 1.0.0 or v1.0.0 |
That release |
| Minimum floor | '>=0.4.2' |
The newest stable release at or above the floor |
| Latest | latest |
The newest stable release |
After the download and the checksum check above:
# exact version
DWP_VIM_VERSION=1.0.0 bash install.sh
bash install.sh --version 1.0.0
# minimum floor: the newest stable release at or above 0.4.2
DWP_VIM_VERSION='>=0.4.2' bash install.sh
# latest stable release
bash install.sh --version latest
Quote the floor, so the shell does not read > as a redirection. Versions resolve to stable release tags only. For a branch or a commit, set DWP_VIM_REF instead (DWP_VIM_REF=main follows main); a version and a ref that disagree are an error.
Containers and CI
In an image or a CI job, where there is no terminal and often no root, download and verify the script, then run it in one step with flags that make the result reproducible:
curl -fsSL -o install.sh https://deepworkplan.com/vim/install.sh && \
curl -fsSL -o install.sh.sha256 https://deepworkplan.com/vim/install.sh.sha256 && \
sha256sum -c install.sh.sha256 && \
bash install.sh --version 1.0.0 --nvim 0.12.5 --skip-packages --strict
--version 1.0.0pins the editor release.--nvim 0.12.5installs that Neovim release into~/.local/opt/nvim-v0.12.5, linked as~/.local/bin/nvimand verified against the SHA-256 that Neovim publishes (Linux and macOS).--skip-packagesinstalls no system package: the image must already provide git, curl and Lua.--strictexits non-zero when the headless plugin install fails or leaves plugins missing. It also checks that every plugin, and pckr, is checked out at the commit the release pins inpckr/lockfile.lua.
Every flag has an environment twin (DWP_VIM_VERSION, DWP_VIM_NVIM, DWP_VIM_SKIP_PACKAGES=1, DWP_VIM_STRICT=1). Add --yes only when the image may already contain a Neovim configuration that should be moved aside.
Requirements and platforms
- Neovim 0.12 or newer. Install it yourself, or let the installer add a verified release with
--nvim X.Y.Z(Linux and macOS). - Lua:
lua,lua5.4orluajit. The installer adds one if it is missing. - macOS, Linux and WSL run the installer. Windows has a documented manual path in the repository README: install Neovim with winget, clone the
v1.0.1tag into%LOCALAPPDATA%\nvim, and runlua install.luafrom Git Bash. - GPL-3.0 licensed: free to use, study and modify.
Update, pin and uninstall
To update, run a newer release’s installer, or run bash install.sh --version latest. Re-running moves an existing DeepWorkPlan Vim checkout to the chosen release, keeps your branches, and never resets local edits: when local changes or commits would be lost, it stops and changes nothing.
To pin a release, use --version (see Choose a version); for a branch or a commit, set DWP_VIM_REF. Prefer a release: releases before v0.4.0 do not include the gestures, the plan browser, the Markdown viewer or this installer.
# pin a specific release, here the previous one
curl -fsSL -o install.sh https://deepworkplan.com/vim/install.sh && \
curl -fsSL -o install.sh.sha256 https://deepworkplan.com/vim/install.sh.sha256 && \
shasum -a 256 -c install.sh.sha256 && \
bash install.sh --version 0.5.1
To uninstall, run lua delete.lua from the configuration directory. It removes the configuration, plugins, Mason data, cache and state, and the font copy the installer made, and it leaves the Neovim binary and your system packages alone.
cd ~/.config/nvim && lua delete.lua
Questions
Will it overwrite my Neovim configuration?
No, not without your approval. When it finds a configuration that is not DeepWorkPlan Vim, an interactive run asks before moving it to ~/.config/previous-deepworkplan-vim. Without a terminal it stops and changes nothing, unless you pass --yes to move it aside unattended. When that backup path already exists, it always stops and changes nothing.
Does it work on Windows?
The installer does not run on Windows. Use the manual path in the repository README, or run the installer inside WSL.
Do I need Deep Work Plan to use it?
No. It is an editor first. It does not install or require the Deep Work Plan skill; the plan browser simply has nothing to list until a .dwp/plans/ folder exists.
How does the v7 vim addon use it?
Deep Work Plan v7 offers the editor as the optional vim addon during onboarding. The addon detects an existing install read-only, through the editor’s addon/surface.json, and offers the pinned, checksum-verified install only with your consent. It never overwrites an existing Neovim configuration without explicit approval, and it is never required.
How do coding agents use it?
It is built for people and for coding agents that live in a terminal. Its keybindings are pinned by contract tests, so muscle memory, and an agent’s expectations, survive updates.
Which version do I get?
The installer installs the release it belongs to — v1.0.1 today — unless you choose another with --version or DWP_VIM_VERSION: an exact version, a >= floor or latest. DWP_VIM_REF takes a branch or a commit; DWP_VIM_REF=main follows main. This page describes release v1.0.1, which ships every feature listed here.
What license is it under, and where does it come from?
GPL-3.0. It is derived from mu-vim by Andrés M Prieto, and the credit stays in the repository.
Source and license
The source is the DeepWorkPlan Vim repository. It is public and GPL-3.0 licensed, derived from mu-vim.
Related kit entries
- Devcontainer — reproducible dev environment (first addon)
- Dailybot — team-visible plan lifecycle reporting (second addon)
- AI Diff Reviewer — local review during plan Final Reviews (fifth addon)
- Herdr — delegate a task to a peer agent in a Herdr pane (v7)
- Agentkit — one command for every terminal coding agent, and headless delegation (v7)