Reqly is a VS Code extension and MCP server for requirements, verification, and traceability in Git repositories. It keeps the source of truth in ordinary Markdown files with YAML frontmatter, so the records are reviewable, diffable, and easy to keep with the product code.
Imagine you are adding a low-battery warning to a device.
Install the generated reqly.vsix in VS Code with Extensions: Install from VSIX....
Open the product repository in VS Code and run Reqly: Initialize Project from the Command Palette. Reqly creates the .reqly/ folders and a small .reqly/AGENTS.md that documents the repository contract.
Use the Reqly activity-bar view, or the CodeLens above an index.md, for the actions below.
Create a requirement and set its status explicitly:
schema: reqly/requirement/v1
id: REQ-0001
title: Show a low-battery warning
status: accepted
relations: []
artifacts: []The file lives at .reqly/requirements/REQ-0001/index.md. Add the requirement text in Markdown and keep related files in that folder, for example:
artifacts:
- "[Battery specification](artifacts/battery-spec.pdf)"Reqly can copy a local file into the item's artifacts/ folder or link a relative path or URL. Links are clickable in VS Code.
Create a child requirement, such as "Display the warning below 10% capacity", and relate it to REQ-0001 with required-by. Reqly maintains the parent's inverse requires relation automatically.
Now the Requirements view shows the product requirement as a parent-first tree. The same view also places linked verifications beneath their requirements. Use its search action to filter requirements and verifications by partial text; separate search terms use AND logic, and matching paths open automatically.
For purely visual organization, create a folder from the Requirements view root, or use the requirement context menu to create one and place that requirement in it immediately. Folder relations are non-normative: rearranging the tree does not change requirement fingerprints. A folder's icon color and check state are derived from the items it contains.
Create a verification and link it to the requirement with verified-by:
schema: reqly/verification/v1
id: VER-0001
title: Check the low-battery warning
status: pass
relations:
- type: verifies
target: REQ-0001
artifacts:
- "[Test recording](artifacts/low-battery-test.mp4)"The verification document contains Procedure, Expected Result, and Evidence sections. Reqly computes the requirement's verification result from its direct verifications and child requirements:
- green check: everything is verified;
- red cross: something failed;
- item icon: evidence is missing or incomplete.
Later, the battery specification changes. Edit the parent requirement or its linked normative data. Reqly detects that the child or verification was based on an older dependency fingerprint and puts it in the impact queue.
Review the affected items, update the requirement or repeat the test, then acknowledge the impact. Reqly refreshes the fingerprint. The Impact Queue toolbar can acknowledge all pending fingerprint changes at once, while a requirement's context menu can acknowledge its own subtree. Broken-reference and cycle warnings remain in the queue until their underlying condition is fixed; draft-parent warnings remain available in diagnostics and on the requirement tree.
Selecting items in the Requirements or Impact Queue tree reuses VS Code's preview editor, preventing navigation from leaving a trail of open tabs. Reqly never stages, commits, pushes, or rewrites Git history; use your normal Git workflow to review and commit the Markdown and YAML changes.
.reqly/
├── requirements/REQ-0001/index.md
│ └── artifacts/
└── verifications/VER-0001/index.md
└── artifacts/
Requirements, verifications, and organizational folders are stable ID-named folders. Folder records live under .reqly/folders, use schema: reqly/folder/v1, an FOL-* ID, and the fixed technical status active. Deleting an item requires confirmation and removes its owned artifacts and incoming relations. Unknown x-* fields and hand-authored Markdown remain yours.
Reqly currently targets VS Code 1.107+ and Node.js 24 LTS. To build the extension locally:
npm install
npm run package:vscodeBefore opening a pull request, run:
npm run check
npm test
npm run buildExtension changes should also pass npm run package:vscode.
Pushes to main run semantic-release after CI passes. A releasable Conventional Commit updates the package versions, builds the VSIX, publishes the core and MCP packages to npm, publishes the VS Code extension to the Marketplace, and creates a GitHub release.
To enable Marketplace publishing, create a Microsoft Entra ID or Azure DevOps personal access token with Marketplace Manage permission and add it as the VSCE_PAT secret in the github-release environment. The token's publisher must be mrpatpat, matching packages/vscode/package.json.
Reqly's universal agent interface is the standalone @mrpatpat/reqly-mcp package. It runs as a local stdio MCP server and works with Codex, Claude, Cursor, and other MCP clients:
Install it directly from the agent's terminal:
Codex:
codex mcp add reqly -- npx -y @mrpatpat/reqly-mcpClaude Code:
claude mcp add reqly -- npx -y @mrpatpat/reqly-mcp[mcp_servers.reqly]
command = "npx"
args = ["-y", "@mrpatpat/reqly-mcp"]The server uses the current working directory as the Reqly repository. Set REQLY_ROOT when the repository is elsewhere.