Three things need to be in place before the first change: the plugin, a coding agent SpecBuddy can launch, and an OpenSpec-initialised project. Ten minutes, most of it waiting for npm.

1. Install the plugin

SpecBuddy is on JetBrains Marketplace: Settings → Plugins → Marketplace, search for SpecBuddy, install, restart. It supports IntelliJ IDEA and the other IntelliJ-based IDEs from 2025.3 onwards.

Or install the Marketplace page from your browser — the Install to … button pushes it into a running IDE.

After the restart you’ll see two new tool windows — Spec Explorer on the left and Spec Cockpit on the right — and a one-time welcome screen. Everything else appears when you open a project that has an openspec/ folder.

2. Connect a coding agent

SpecBuddy does not ship an AI model. It drives an agent CLI you already have — and installs a small integration component so the agent can run headless inside the IDE.

Supported agents, and what SpecBuddy adds for each:

You need Node.js on your PATH for the npm components.

The first-run picker

You don’t have to configure anything up front. The first time you start a session without a configured agent, SpecBuddy scans your PATH and opens Set Up Coding Agent: a list of the agents it found, one recommended. Pick one and press Install & Continue — the integration component is installed and checked in the SpecBuddy Setup tool window at the bottom, and the launch continues when it is green. If nothing is detected, the picker sends you to Settings instead.

The picker also offers to fix the project when something is missing — see Initialise OpenSpec below.

Agent profiles

Settings → Tools → SpecBuddy holds a table of agent profiles. A profile is one way of launching an agent: the preset (Claude Code, Codex CLI, OpenCode, Cursor, Custom), the executable, the integration component, and the defaults for new runs — model, effort and permission mode. The lists of models and modes are fetched from the agent itself, so they are whatever your CLI version supports; an empty value means “the agent’s default”.

One profile is the default and is used for every launch. You can keep several — say, Claude Code on sonnet for everyday tasks and opus for proposals — and switch between them per session from the Agent Log.

Two settings on that page change how sessions behave and are worth deciding now:

• Always run the agent in auto mode. The agent runs with its own auto/accept-edits mode, so it stops asking for approval on routine file edits and commands. This is the CLI’s own mode — it still refuses what it considers dangerous. Off by default; you can also switch the permission mode per session.
• Always run steps in a dedicated worktree. Skips the “current branch or worktree?” question and always isolates task runs. Off by default — see Worktrees and git.

3. Initialise OpenSpec in the project

SpecBuddy runs the OpenSpec workflow through OpenSpec’s own CLI and slash commands (/opsx:propose, /opsx:apply, /opsx:sync, /opsx:archive, /opsx:explore). It never installs the CLI for you, but it does notice when the project is not set up and offers to fix it.

If your project already has an openspec/ folder and the openspec command is on your PATH, you are done — skip to the Quickstart.

Otherwise:

npm install -g @fission-ai/openspec

Then either run openspec init yourself in the project root, or let SpecBuddy do it: on the first launch the Set Up Coding Agent picker shows a checkbox Initialize OpenSpec in the project (“Runs openspec init — creates the openspec/ folder in your working copy”), and a later launch that finds the agent’s slash commands missing offers Install OpenSpec Integration, which runs openspec init --tools <your agent> and shows the output in a build tab. Restart the IDE afterwards so the newly installed slash commands are picked up.

openspec init writes the agent’s command files into your working copy (for Claude Code that is .claude/commands/opsx/…). Commit them with the project — everybody who opens it gets the same commands.

4. Check

Open the Spec Explorer. With an initialised project you see a Main Specs section (empty if nothing has been archived yet), and the + button on its toolbar offers New OpenSpec Change. That is where the Quickstart starts.

If a launch fails, the message tells you which of the three pieces is missing — the agent executable, its integration component, or the OpenSpec CLI — and where to fix it. Nothing else is required: no API keys in the IDE, no hooks to configure by hand.