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 (v7.0.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 v0.5.0.

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. It is a curated Neovim configuration — language servers, completion, linting, 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.

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.

What you get

Five features, each one keystroke away.

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.

Press Enter on a plan 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/.

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.

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 v0.5.0, the release this page describes, unless you choose another version.

curl -fsSL -o install.sh https://deepworkplan.com/vim/install.sh && \
echo "4890c140528d6b8d19b6bbc4102051e0b9dce2e26f43a693bdeab2e1cd8e196b  install.sh" | shasum -a 256 -c && \
bash install.sh

In order, the installer:

1. Checks your OS and package manager, and installs git, curl and a Lua interpreter if any are missing (none with --skip-packages).
2. Resolves the version: its own release, or the one --version asks for.
3. With --nvim X.Y.Z, installs that Neovim release into ~/.local/opt, verified against the SHA-256 that Neovim publishes.
4. Asks before touching an existing Neovim configuration. Without a terminal, it stops and changes nothing, unless --yes tells it to move that configuration aside.
5. Clones the repository into ~/.config/nvim, or updates it when it is already there.
6. Runs the repository’s own lua install.lua.
7. 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 v0.5.0 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, v0.5.0. 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:

After the download and the checksum check above:

# exact version
DWP_VIM_VERSION=0.5.0 bash install.sh
bash install.sh --version 0.5.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 0.5.0 --nvim 0.12.5 --skip-packages --strict

• --version 0.5.0 pins the editor release.
• --nvim 0.12.5 installs that Neovim release into ~/.local/opt/nvim-v0.12.5, linked as ~/.local/bin/nvim and verified against the SHA-256 that Neovim publishes (Linux and macOS).
• --skip-packages installs no system package: the image must already provide git, curl and Lua.
• --strict exits non-zero when the headless plugin install fails or leaves plugins missing.

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.4 or luajit. 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 v0.5.0 tag into %LOCALAPPDATA%\nvim, and run lua install.lua from 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.4.2

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 — v0.5.0 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 v0.5.0, 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)