View scripts with their documentation and diagrams side by side, inside VS Code. It also shows the flows (process
diagrams) that tie the scripts together. Read, edit, compare and commit the docs and diagrams without leaving the
editor. Claude Code writes the docs and diagrams; people review and adjust them.
For a step-by-step guide with pictures, run Script Documentation Tool: Open the How-To Guide from the Command
Palette, or click Open the how-to guide on the tool's Help page.
Features
- Scripts, docs and diagrams side by side. Click a doc step or a diagram box to highlight its lines in the script,
and the other way round.
- Flows: process diagrams whose boxes link to the scripts they run. Organise them in subfolders.
- Edit in place: docs as they read (not as raw Markdown), and diagrams with drag and drop. Everything saves as you
go, with undo and redo.
- Out-of-date warnings: the doc and the diagram each remember which version of the script they describe, and say
when the script has moved on. An amber ! marks them in the Explorer.
- Changes: see what you changed, drawn (red before, green after) or as JSON or Markdown. Then commit and push a
script with its doc and diagram in one step, with a warning if the docs describe an earlier version.
- History: every commit that changed a script, its doc, its diagram or a flow, and what each one changed, with
all three side by side for a commit that changed a script and its docs together. Restore
an older version in one click.
- Settings for each repo: where the scripts, docs, diagrams and flows are, which files count as scripts, and the
main branch. Store them in the repository to share them, or in your user settings.
- Works in any window: open the repo folder, or set it once and open the tool from any VS Code window, even one
with no folder open.
- Claude Code support: one command sets up Claude Code to write and update the docs and diagrams.
- Light and dark themes, search across everything, PDF and Markdown export.
What a repo holds
| File |
What it is |
Default place |
| A script |
Any file in the scripts folder, at any depth |
Scripts/Identity/Disable-InactiveUsers.ps1 |
| Its doc |
What the script does, step by step, in Markdown |
Script-Docs/Disable-InactiveUsers.ps1.md |
| Its diagram |
Every step, branch and error path of the script |
Script-Diagrams/Disable-InactiveUsers.ps1.json |
| A flow |
A process such as onboarding, with the scripts it runs |
Flow-Diagrams/HR/Onboarding.json |
| Settings (optional) |
Other folder names, which files aren't scripts, the main branch, named colours, flow rows |
script-documentation-tool.settings.json |
A doc and a diagram belong to a script by its file name, wherever the script sits. Everything is a file in your local
clone: viewing never changes a file, your edits save to your clone, and nothing reaches the remote until you commit
and push.
Requirements
- VS Code 1.141 or newer.
- Git (Git for Windows).
- For Claude Code's tools only: Node.js, and Chrome or Edge.
Getting started
- Install: in the Extensions view (Ctrl+Shift+X), search for Script Documentation Tool and click Install.
- Click the Script Documentation Tool icon in the Activity Bar. It's there in every window.
- Point it at your repo, either way:
- Open the repo folder in VS Code and trust it when asked. The tool shows the folder VS Code has open.
- Or choose the repo folder once: with no repo open, the tool shows a start page. Click Choose a Folder… and
pick your local clone. From then on, any VS Code window without a repo of its own shows that one, even with no
folder open. This is the Repo Folder setting; it's also on the tool's Settings page.
A folder counts as a repo when it has a script-documentation-tool.settings.json, or the default folders: Scripts
with Script-Docs, Script-Diagrams or Flow-Diagrams beside it. For a repo with other folder names, click Use
This Folder or Choose a Folder… on the start page and enter them on the Settings page.
Updating: VS Code updates the extension automatically, like any other. Reload VS Code when it asks.
Documenting a script with Claude Code
Run Script Documentation Tool: Set Up Claude Code once per PC and repo. It copies Claude Code's guide and tools to
%USERPROFILE%\.script-documentation-tool, adds a short section to the repo's CLAUDE.md, and sets Claude Code's
permissions (.claude/settings.json, plus a check in .claude/settings.local.json) so it can change only the docs,
script diagrams and flows folders. Then ask Claude Code, for example:
Document Scripts/Identity/Disable-InactiveUsers.ps1
Claude reads the script, writes the doc and the diagram, checks them, lays the diagram out and looks at a picture of
it. Last, it stamps both with the script's fingerprint, so the tool can tell later when the script has changed. Other
requests: "Update the docs for Set-E5Hold.ps1. Change: Legal asked for holds to last 7 years." (after the script
changed; the reason goes into the doc's Change history, dated, newest first), "New flow: Offboarding" followed by the
steps, "Set-E5Hold.ps1 was renamed to Set-LegalHold.ps1". Review the result in the tool, then commit it from its
Changes screen.
Commands
| Command |
Does |
| Script Documentation Tool: Open |
Opens the tool, or brings it forward |
| Script Documentation Tool: Choose a Folder… |
Opens a folder in the tool and makes it the default repository |
| Script Documentation Tool: Use This Folder |
Opens the folder open in this window in the tool, at Settings if it isn't recognised |
| Script Documentation Tool: Set Up Claude Code |
Gives Claude Code the instructions and tools to document this repo, and keeps it to the docs, script diagrams and flows folders |
| Script Documentation Tool: Open the How-To Guide |
The full guide, with pictures |
| Script Documentation Tool: Reload |
Loads the tool again |
| Open in Script Documentation Tool |
On a script, doc, diagram or flow's editor tab or Explorer menu: shows it in the tool |
| Open Visual Diff |
On a changed doc, diagram or flow in Source Control: shows its changes drawn |
Settings
- Repo Folder (
scriptDocumentation.repoFolder): the full path of your local clone. Windows whose open folder
isn't a repo, or that have no folder open, show this one. Empty (the default): only the folder open in VS Code. It's
a per-PC setting, so a workspace's own settings can't change it.
- Open Button (
scriptDocumentation.openButton): where the button that opens the tool shows: the Activity Bar
(activityBar, the default), the status bar (statusBar), or both.
Everything else, from folders to the theme, is on the tool's own Settings page (the gear).
Keyboard
While the tool has focus, Ctrl+F searches the tool, Ctrl+B hides or shows its sidebar, and Alt+Left goes back. With
focus in VS Code's own side bar or panel, those keys are VS Code's. The tool's Help page lists every shortcut.
Tips
- A window of its own: right-click the tool's tab → Move into New Window. Handy on a second screen.
- Fetching: turn on VS Code's Git: Autofetch setting and the tool's status bar always knows about new commits
on the remote.
- More room: Zen Mode (Ctrl+K Z) hides VS Code's side bars and status bar around the tool.
Troubleshooting
- The start page shows instead of your repo: the open folder isn't a recognised repository and no default
repository is set. Click Use This Folder or Choose a Folder….
- "Trust this folder to use Script Documentation Tool": VS Code is in Restricted Mode for this folder. Use
Manage Workspace Trust and trust it.
- Git not found: install Git for Windows, then reload VS Code.
- Fetch failed: usually no network, or a sign-in is needed. Click Fetch in the tool's status bar and sign in
when Git Credential Manager asks.
License
MIT.
| |
