Installation
Install SpecSafe and configure it for your AI coding tool.
Prerequisites
- Node.js >= 18
That's all you need. SpecSafe has no other system dependencies.
Install globally (recommended)
Install SpecSafe as a global command:
npm install -g @specsafe/cliThen initialize your project:
specsafe initThe init command is interactive -- it will:
- Ask for your project name (defaults to the current directory name)
- Auto-detect which AI tools you use (by looking for
.claude/,.cursor/, etc.) - Let you select which tools to install skills for
- Ask for your test framework (vitest, jest, pytest, go test)
- Create all project files and install the selected tool skill files
Local installs won't expose the command
Running npm i @specsafe/cli (without -g) installs the package locally but does not add specsafe to your PATH. Use npm install -g @specsafe/cli for the global command, or use npx @specsafe/cli as a one-off alternative.
Supported AI tools
SpecSafe supports 8 AI tools. During specsafe init, you select which ones to install:
| Tool | Detected by |
|---|---|
| Claude Code | .claude/ directory |
| Cursor | .cursor/ directory |
| OpenCode | .opencode/ directory |
| Aider | .aider.conf.yml file |
| Zed | .zed/ directory |
| Gemini CLI | .gemini/ directory |
| Continue | .continue/ directory |
| Antigravity | .agent/ directory |
Adding tools later
If you need to add a tool after initial setup, you can run specsafe install <tool-name> separately (e.g., specsafe install cursor).
What gets created
After running init and install, your project will contain:
specs/-- Directory for active, completed, and archived specsPROJECT_STATE.md-- Single source of truth for all spec statusspecsafe.config.json-- Project configuration- Tool-specific skill files -- For example, Claude Code gets
.claude/skills/specsafe-*/SKILL.mdfiles
See Project Structure for the full breakdown.
Verify the installation
Run the doctor command to confirm everything is set up correctly:
specsafe doctorThis checks that your configuration is valid, skill files are in place, and the specs/ directory structure exists.
Troubleshooting
If specsafe doctor reports missing skill files, re-run specsafe install <tool> for your AI tool. If you see configuration errors, check that specsafe.config.json exists in your project root.