Local Workflows

Your project's dev pipeline and your specs, both run from inside VS Code.

Define the commands you run all day in a .local-workflows/tasks.yml next to your code, and run any of them from a native sidebar with a live, GitHub Actions-style run panel and dependency graph — no CI, no Docker, no leaving the editor. Then use the same engine for spec-driven development: AI-drafted requirements, design and plan, a human decision between each phase, and the whole process committed to git.

📖 Full documentation →

Why this exists

Every project ends up with the same handful of commands you run all day — reset a database, build a client, start a dev server, kill stray processes — and none of the usual options fit. npm run scripts and Makefiles have no dependency graph and no visual feedback. CI can run a pipeline, but only after a commit and a push. act needs Docker to replay a workflow that was never meant to run on your laptop.

This runs that pipeline locally, instantly, with the run experience CI gives you — and then reuses the same engine for the other half of the job: turning a work item into requirements, a design, a plan and code, with a human decision at every phase boundary.

One rule holds it together: AI produces data, and a file you wrote and reviewed decides what happens to it. An AI task writes a value; it never picks the action.

⚠️ Caution

• run: executes arbitrary shell commands, with no sandboxing — the same risk class as npm run or make. A workflow file travels with a repository, so cloning an untrusted repo and clicking a task is a real execution vector. Plugins you write yourself are different: those run in their own process under Node's permission model, confined to their own directory.
• workspace/root/cwd are not a sandbox. They decide where a process starts, not what it can reach.
• AI agent tasks write to your working tree, and SDD's implement phase hands tasks to a coding agent. Git is your safety net; review what they change.
• Young project. The engine is covered by ~1,450 unit tests; the VS Code integration is verified by hand. Expect rough edges.
• Not intended for a mixed-OS team.

Multi-root workspaces

Open a .code-workspace and definitions come from three places: each repository's own .local-workflows/, one beside the workspace file shared by all of them, and your profile's. The narrowest wins a clash.

Anything that belongs to no repository — a shared task, a profile workflow — asks which folder to run in each time you run it, and remembers nothing. Specs get one home for the whole workspace instead of being scattered across every repository in it.

Open a plain folder and none of that applies; it behaves as it always has.

Requirements

VS Code 1.103+. That floor is not arbitrary: run history is kept in SQLite through Node's built-in node:sqlite, which older builds do not have. On a runtime without it the extension still starts, but history lives in memory and is gone when the window closes — and it says so rather than losing it quietly.

PowerShell for tasks that declare shell: pwsh.

For AI tasks and spec-driven development: a GitHub Copilot sign-in and the GitHub Copilot CLI — npm install -g @github/copilot. That is the CLI, not the Copilot editor extension; this drives the CLI directly and never calls the extension. It is ~340 MB per platform, so it is a prerequisite rather than something bundled.

Everything else works without any of it.

Documentation

Everything — installing, your first pipeline, both file formats, writing your own plugins and spec styles, and the full schema reference — lives at local-workflows.github.io.

Inside the editor, the Command Palette also has Local Workflows: Schema Reference.

License

The extension is free to use — for anything, personal or commercial, on as many machines as you like. It is not open source, and the source is not distributed.

What you install is the built extension. You may not copy, modify, redistribute or republish it, or build a derivative work from it. Everything you author — your tasks.yml, your .local-workflows/ definitions and prompts, your specs, your own plugins — is entirely yours and covered by none of this.

Provided as-is, with no warranty. It runs shell commands you or your repository author, and it launches AI agents that modify files in your working tree; reviewing what those agents change is on you.