The Spec Explorer is the map of the project’s OpenSpec work. Open it from the left tool-window bar; it is where you start a change, see which one the agent is working on, and get back to a session’s log.

Sections

The tree has up to four top-level sections; a section that would be empty is not shown.

  • Change Specs — every change under openspec/changes/ (except the archive). Changes with a live agent session sort to the top; the rest by how recently you worked on them, so the change you touched yesterday is above the one from last month.
  • Main Specs — the canonical specs in openspec/specs/<capability>/spec.md, one row per capability. These are what a change’s deltas are merged into on sync.
  • Archive — changes under openspec/changes/archive/. Read-only in the sense that SpecBuddy offers no actions on them, but their documents, logs and run history are all still there.
  • Agents — your configured agent profiles, and Connect Agent… to add one. Double-click a profile to open its settings. When the agent CLI reports remaining usage (Claude Code does), it is shown next to the name.

A change that is currently running as a plain agent session without a directory yet — the first seconds of a propose — appears as a transient top-level Agent session node until the change exists.

Reading a change row

▸ ◉ add-full-text-listing-search   3/7 Tasks   ⎇ feature/add-full-text-listing-search

From left to right:

  • Icon — the document icon, with a small badge for the session state:
    • no badge — idle;
    • working badge — the agent is running;
    • awaiting-input badge — the agent asked something and is waiting for you;
    • review badge — a run finished and its result waits for you (accented until you open the log or review, muted afterwards);
    • interrupted / failed badges — the run stopped early; the same accented-until-viewed rule applies.
  • Name — the change id, which is also its directory name.
  • State badge — one of:
    • Draft — the directory exists but has no proposal yet;
    • Spec — a proposal exists but no tasks.md yet;
    • 3/7 Tasks — how many ## sections of tasks.md are done;
    • Running: ## 2. Search query, Review: …, Failed: …, Interrupted: … — while a session is live, what it is doing. The operation is the task heading, or propose, refine, sync, archive for document runs.
  • ⎇ branch — shown when the change has a dedicated worktree; the branch it is on.

When the panel is narrow the worktree badge is dropped first, then the state badge is truncated — widen the tool window to see everything.

Expand the row to see the change directory’s actual contents — proposal.md, design.md, tasks.md, the specs/ deltas — and open any of them with a double-click. The list updates as the agent writes files, so a propose in progress visibly fills in.

Toolbar

  • + — New Spec: a chooser between New OpenSpec Change and New SpecBuddy Spec (the plugin’s own plain-Markdown format, not covered here).
  • Select Opened Spec — reveals the row for the document in the active editor. Handy when you have a worktree copy of a file open: it selects the change, not a duplicate.
  • ⚙ — opens SpecBuddy’s settings; the menu also holds Reinstall Hooks and Skills, which reconciles the agent integration after an upgrade.
  • Expand all / collapse all.

Context menu

Right-click a change:

  • Show Agent Log — opens the change’s log tab: the live session if one is running, otherwise the last persisted log. Double-clicking a row with a live session does the same.
  • Create Worktree — for a change that has no worktree yet: create one now rather than at the first task run.
  • Open Worktree Window — opens the worktree as a second IDE window. You rarely need this; see Worktrees and git.
  • Commit, Merge — the worktree git operations, same as the Cockpit’s.
  • Remove Worktree — deletes the worktree and its branch checkout. Offered only when SpecBuddy considers it safe; the confirmation spells out that uncommitted, unmerged work in it is lost.

Empty state

With no changes and no specs the panel says so — No specs in specs/ or changes in openspec/changes/ — and the + button is the way forward. If the project has no openspec/ folder at all, see Install and set up.