fission-ai / openspec

Requires Node.js 20.19.0 or higher. Homebrew installs it as a dependency.

Install OpenSpec globally:

npm install -g @fission-ai/openspec@latest

Or install the official Homebrew formula on macOS or Linux:

brew install openspec

Then navigate to your project directory and initialize:

cd your-project
openspec init

Want your AI to do it? Paste the setup prompt into your coding assistant — it installs the CLI, runs openspec init, and verifies the result.

Now talk to your AI:

• Not sure what to build yet? Start with /opsx:explore, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before any code gets written. (Quickstart)
• Already know what you want? Go straight to /opsx:propose <what-you-want-to-build>.

Both are in the default profile. If you want the expanded workflow (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard), select it with openspec config profile and apply with openspec update.

/opsx:propose is the canonical name; your tool may spell it /opsx-propose (Cursor, GitHub Copilot), @opsx-propose (Amazon Q) or $openspec-propose (Codex). openspec init prints the right form for the tools you picked — see Supported Tools.

[!NOTE] Not sure if your tool is supported? View the full list – we support 30+ tools and growing.

Also works with Homebrew, pnpm, yarn, bun, and Nix. See installation options.

You need Node 20.19+ and pnpm.

pnpm install
pnpm build              # tests run against the build output
pnpm test
pnpm exec tsc --noEmit
pnpm lint

Those four commands are what CI runs, so a green local run means a green CI run.

Run pnpm changeset if your change affects users, and commit the file it generates.

Keep the CLI's startup fast

Editors, agents and OpenSpec Desktop run the CLI many times, and each call pays for every module it loads before the command runs. Before this rule, openspec --version loaded 485 modules: about 0.5 s per call on a Windows machine. So a command loads only the command definitions and its own code:

• Definitions (name, options, help text) go in src/cli/index.ts or src/cli/commands/<name>.ts. Import nothing heavy there: no zod, yaml, tinyglobby, ora, and no other command's code.
• The command's code goes in src/commands/<name>.ts or src/core/, loaded inside the action with await import().

test/cli-e2e/startup-modules.test.ts checks which modules each command loads, and fails if a definition starts pulling in an implementation. When you add a command, add it to that test's list.