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.4.2.

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.

Plan
Tasks
Gates
Done

In the editor

Plan browser SPC P Every plan under .dwp/plans/, grouped by status, with progress. Read-only.

Markdown viewer SPC m p · SPC m r Preview or render a plan’s Markdown files without leaving Neovim.

The editor sits beside the loop: it shows where each plan stands and lets you read its files. It never writes under .dwp/.

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 Command index Generated from the live keymaps

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

The index lists every mapping the editor has, because it is generated from the live keymaps. A few of the rows are shown here.

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.
Deep Work Plan browser	`SPC P`	A sidebar over the plans in your repository, grouped by status with progress bars, and a reader for one plan.
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.

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.4.2, the release this page describes; DWP_VIM_REF=main bash install.sh follows the moving main branch instead.

bash

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

Consent first: an existing Neovim configuration is never overwritten without your approval. The installer asks, and when it cannot ask it stops and changes nothing.

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: c3c844bb5a9290b65d50dd484fa7b2a0f22b895ecb693f14e1661992f3f19a5e; 22776 bytes · 513 lines

On macOS, use shasum -a 256 install.sh for the second step.

To install a specific branch, tag or commit, set DWP_VIM_REF. Older tags 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.
Asks before touching an existing Neovim configuration. Piped without a terminal, it stops and changes nothing.
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, so there is no quit-and-reopen step.

The script served here is a byte-identical copy of install.sh at the v0.4.2 tag. To read it first, download it with curl -fsSL https://deepworkplan.com/vim/install.sh -o install.sh, compare its SHA-256 with the value shown above, read it, then run bash install.sh.

Requirements and platforms

Neovim 0.12 or newer. Install Neovim first; the installer does not install it.
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 repository 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. Re-running moves an existing DeepWorkPlan Vim checkout to that installer’s release, keeps your branches, and never resets local edits: when local changes or commits would be lost, it stops and changes nothing.

To install another tag, a branch or a commit, set DWP_VIM_REF. Prefer a tag: releases before v0.4.0 do not include the gestures, the plan browser, the Markdown viewer or this installer.

curl -fsSL -o install.sh https://deepworkplan.com/vim/install.sh
shasum -a 256 install.sh
DWP_VIM_REF=v0.4.0 bash install.sh

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, or when that backup path already exists, it 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.4.2 today — unless you set DWP_VIM_REF; DWP_VIM_REF=main follows main. This page describes release v0.4.2, 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.

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)