# How to Set Up a Development Environment for OpenSpec: Complete Setup Guide

> Quickly set up your OpenSpec development environment. Follow this guide to install Node.js and pnpm, clone the repository, and build OpenSpec for local development.

- Repository: [Fission/OpenSpec](https://github.com/Fission-AI/OpenSpec)
- Tags: getting-started
- Published: 2026-06-28

---

**To set up a development environment for OpenSpec, install Node.js ≥20.19 and pnpm, clone the Fission-AI/OpenSpec repository, run `pnpm install` and `pnpm run build`, then launch the CLI via `node bin/openspec.js`.**

OpenSpec is a TypeScript-based CLI tool maintained by Fission-AI that requires a modern Node.js runtime and specific build steps to compile source code from the `src/` directory into the executable `dist/` folder. Whether you are contributing to the core codebase or extending functionality for AI-driven spec workflows, following the official setup ensures compatibility with the Vitest test suite and the containerized development workflow.

## Prerequisites for OpenSpec Development

Before cloning the repository, verify your system meets the baseline requirements defined in [`package.json`](https://github.com/Fission-AI/OpenSpec/blob/main/package.json) → `engines`.

**Required tools:**

- **Node.js ≥20.19.0** – The runtime minimum specified in the engine constraints. Verify with `node --version`.
- **pnpm** – The default package manager used in scripts throughout the repository. Enable it via Corepack: `corepack enable && corepack prepare pnpm@latest --activate`.
- **Git** – Any recent release for cloning and version control.
- **Docker + VS Code** (optional) – For the containerized workflow defined in [`.devcontainer/devcontainer.json`](https://github.com/Fission-AI/OpenSpec/blob/main/.devcontainer/devcontainer.json).

While npm, yarn, and bun are supported alternatives, all subsequent commands use pnpm for consistency with the project's internal tooling.

## Clone the Repository and Install Dependencies

Start by cloning the repository and entering the project directory:

```bash
git clone https://github.com/Fission-AI/OpenSpec.git
cd OpenSpec

```

Install dependencies using pnpm:

```bash
pnpm install

```

This command triggers the `postinstall` hook configured in [`scripts/postinstall.js`](https://github.com/Fission-AI/OpenSpec/blob/main/scripts/postinstall.js), which configures telemetry settings and validates the Node.js version meets the ≥20.19 requirement.

## Build the TypeScript Source

OpenSpec ships with TypeScript source in `src/` that must be compiled before execution. Run the build script defined in [`package.json`](https://github.com/Fission-AI/OpenSpec/blob/main/package.json):

```bash
pnpm run build

```

The build process (orchestrated by [`build.js`](https://github.com/Fission-AI/OpenSpec/blob/main/build.js)) compiles all TypeScript files into the `dist/` directory and prepares the [`bin/openspec.js`](https://github.com/Fission-AI/OpenSpec/blob/main/bin/openspec.js) entry point. The [`tsconfig.json`](https://github.com/Fission-AI/OpenSpec/blob/main/tsconfig.json) file governs compiler options during this step.

## Run the CLI Locally

Validate your development environment by executing the CLI locally:

```bash
pnpm run dev:cli

```

This npm script builds the project and immediately launches the interactive CLI. Alternatively, after a successful build, run the binary directly:

```bash
node bin/openspec.js --help

```

You should see the help output listing available `/opsx:` slash commands and sub-commands. This [`bin/openspec.js`](https://github.com/Fission-AI/OpenSpec/blob/main/bin/openspec.js) file is the same entry point referenced when installing the package globally via `npm install -g @fission-ai/openspec`.

## Execute the Test Suite

Confirm your environment matches CI expectations by running the Vitest-powered test suite:

```bash
pnpm test          # Run all tests once

pnpm test:watch    # Watch mode for iterative development

pnpm test:coverage # Generate coverage reports

```

Tests reside in the `test/` directory, covering both unit logic (such as [`vocabulary-sweep.test.ts`](https://github.com/Fission-AI/OpenSpec/blob/main/vocabulary-sweep.test.ts)) and end-to-end CLI scenarios in `cli-e2e/`. Successful execution proves that Node.js, pnpm, and the compiled `dist/` artifacts are functioning correctly.

## Optional: Use the VS Code DevContainer

For a reproducible, isolated environment, use the included DevContainer configuration found at [`.devcontainer/devcontainer.json`](https://github.com/Fission-AI/OpenSpec/blob/main/.devcontainer/devcontainer.json).

**Setup steps:**

1. Open the repository folder in VS Code.
2. When prompted, select **"Reopen in Container"** or run the command `Remote-Containers: Reopen Folder in Container`.

The container automatically provisions Node.js 20, pnpm, Git, and the GitHub CLI. It executes `pnpm install` via the `postCreateCommand`, ensuring the environment is ready immediately upon startup. This approach eliminates "works on my machine" issues by matching the Linux-based CI runner environment.

## Summary

- **Install Node.js ≥20.19** and enable **pnpm** via Corepack to meet engine requirements specified in [`package.json`](https://github.com/Fission-AI/OpenSpec/blob/main/package.json).
- **Clone** the Fission-AI/OpenSpec repository and run `pnpm install`, which executes [`scripts/postinstall.js`](https://github.com/Fission-AI/OpenSpec/blob/main/scripts/postinstall.js) for telemetry setup.
- **Build** the TypeScript source with `pnpm run build` to populate the `dist/` directory.
- **Run** the CLI locally using `pnpm run dev:cli` or `node bin/openspec.js` to verify functionality.
- **Test** your setup with `pnpm test` to ensure compatibility with the Vitest suite.
- **Containerize** your workflow using the VS Code DevContainer for a fully reproducible Linux environment.

## Frequently Asked Questions

### What Node.js version is required for OpenSpec development?

OpenSpec requires **Node.js ≥20.19.0** as specified in the `engines` field of [`package.json`](https://github.com/Fission-AI/OpenSpec/blob/main/package.json). The [`scripts/postinstall.js`](https://github.com/Fission-AI/OpenSpec/blob/main/scripts/postinstall.js) hook validates this version during installation and will warn if your runtime is outdated.

### Can I use npm or yarn instead of pnpm?

Yes, though **pnpm** is the default package manager used in the project's scripts. You can substitute `pnpm` with `npm` or `yarn` in most commands (e.g., `npm install` instead of `pnpm install`), but the Corepack-enabled pnpm workflow is the officially tested path for contributors.

### How do I run OpenSpec without installing it globally?

After building the project with `pnpm run build`, execute the local binary directly: `node bin/openspec.js --help`. Alternatively, use `pnpm run dev:cli` to build and launch in one command. This avoids polluting your global npm packages while developing.

### What is the purpose of the `.devcontainer` directory?

The [`.devcontainer/devcontainer.json`](https://github.com/Fission-AI/OpenSpec/blob/main/.devcontainer/devcontainer.json) file defines a **Docker-based development environment** for VS Code that includes Node.js 20, pnpm, Git, and the GitHub CLI. Opening the repository in this container ensures a clean, reproducible setup identical to the CI environment, eliminating dependency conflicts across different host machines.