AI agent integration
A button on the spec file's toolbar opens a terminal session with an AI coding agent. The plugin remembers that session against the spec file, so a later click brings back this spec's own session instead of starting another one beside it.
Claude Code and GitHub Copilot CLI are both supported; pick one from the button's dropdown. The
agent's own CLI has to be on your PATH, and the button is opt-in: switch on Show a "Launch AI
agent" button on the toolbar, and keep the editor toolbar itself
enabled.
<The Launch AI Agent button on the toolbar with its dropdown open, showing the choice of agent and the session commands.>
Starting and resuming a session
A click with no session tab open always starts a fresh session — it never silently picks up something from last week. Resuming is deliberate: Resume a Past Session… in the dropdown lists this spec's previous sessions for the active agent, newest first, and New Parallel Session opens another beside one already running.
<The Resume a Past Session… popup listing this spec file's earlier sessions for the active agent, newest first, with their dates.>
You can see which of the two you will get before you click. The button's icon is grey while no session is live, and purple once one is running and a click would reopen its tab.
<The two states of the button side by side: grey with no session running, purple with one running.>
The session starts with one instruction already sent: read this spec file, then wait. The agent therefore has the spec in context before you type anything, and it does nothing until you ask.
Read this SpecBinder spec file and wait for my instructions: src/test/java/…/ShoppingCart.specb
The path is relative to the directory the session runs in, described below, and the tab is named after the spec file. You can see the whole command in the terminal tab, including the session id the plugin assigns so it can find this session again.
<A terminal tab just after launch, showing the command with the session id and the seed instruction, and the agent's reply confirming it has read the spec file.>
The session's working directory is the root of the module the spec file belongs to, and not the folder the spec file happens to sit in. That way the agent starts with the project context it needs, whatever spec file you launched it from.
Where the spec-to-session link is kept
By default the link lives in IDE storage and your spec file is untouched.
Turning on Store the agent session id in the spec file, under Settings → Tools → SpecBinder → Agent integration, writes the id into the spec file itself as a comment line at the top. That matters if you use git worktrees: each worktree opens as its own IDE workspace with its own project storage, and no worktree can read what another one stored. Keeping the id in the file lets every worktree reopen the same session, and the link travels with the spec file itself, to another clone or another machine.
The marker is one comment line per session, with the id first.
<The top of a spec file with two session marker comment lines above the
Feature:line, each with its id first and a note of your own after it.>
The agent state on the spec file icon
Turn on Badge spec file icons with the linked agent's working state, under Settings → Tools → SpecBinder → Agent integration, and a spec file with a linked session carries a small diamond over its file icon:
| Badge | Meaning | |
|---|---|---|
| <spec file icon with a pulsing orange diamond over it> | Pulsing orange | The agent is working |
| <spec file icon with a filled green diamond over it> | Green | It needs your input or permission |
| <spec file icon with a filled grey diamond over it> | Grey | It has finished its turn |
| <plain spec file icon, no diamond> | None | No live session |
This is Claude Code only at present, because Claude Code is the one that reports its state back. Copilot sessions still work, they just stay unbadged.
The reporting is set up per session, and your own Claude configuration is never edited.
<The Project view with two spec files badged — one pulsing orange, one green — over their ordinary status icons.>
Two further options in the dropdown
Auto-Select This Spec's Terminal Tab — off by default — keeps the Terminal tool window in step with the editor. Open another spec file, or click into its editor tab, and the Terminal automatically switches to that spec file's own agent session tab.
Auto-Enable Remote Control — also off by default, and Claude Code only — adds
--remote-control to sessions started from the button, so you can watch or drive them from
claude.ai or your phone. It applies to resumed sessions too.