JirAI: Virtual board
The virtual board shows your AI agent's own plan in an IDE editor tab: one card per phase, moving from To Do to In Progress to Done while the agent works.
It works for one agent or for several subagents working together.
It is not a Jira board. The board is kept in the IDE on your machine, and it writes nothing to your repository.
It writes nothing to Jira either, except a change you approve on it. See Approve the agent's Jira changes.
Watch the virtual board demo on YouTube.
Start a board
The board needs the IDE's MCP server; see Turn on the agent tools.
You do not need to be signed in to Jira, except for a board linked to a Jira issue.
Ask your agent for a virtual board
In your agent's main chat session, do one of the following:
Type
/use-virtual-board($use-virtual-boardin Codex). This needs the JirAI agent skill.Without the skill, type: Use the virtual board tools exposed in the IDE tools. If the agent does not find the tools, add …exposed in the IDE via the JirAI plugin.
Give the agent its task. From then on, it uses the board whenever it runs subagents or works through a plan with phases.
The board opens in a tab in the background, so it does not take your editor away. Click Show in the notification to bring it forward.
To work on a Jira issue that has children, use /work-on-jira-issue instead; see A board linked to Jira.
In a later session, ask the agent to continue the plan, and check for an existing virtual board to resume a board.
The agent's tools are in their own JirAI virtual board group under ; turn the group off there if you do not want them.
Read the board
The header shows the board name, the stage strip (Spec, Plan, Implementation, PR), and Open spec and Open plan when the agent named those files.
It also shows when the agent last reported, for example Agent updated 2 min ago.
When the IDE's MCP server is off, the header reads Agent channel unavailable — the IDE's MCP server is off.
Each card shows the phase's number or label, its title, the steps count and, while the phase runs, what the agent is doing now.
The steps count is colored by real progress. When the agent never reported its steps, it reads N steps · not reported and falls back to the ticked checkboxes in the plan file.
A card shows an icon for the agent's AI provider. An In Progress card's mark spins while the agent reports and stops after 5 quiet minutes.
An In Progress card with no report for 20 minutes shows No update for N min, then hours, then days.
A card warns Plan file shows this done; the agent did not report it when the plan's checklist is ticked but the agent has not reported the phase.
A blocked phase shows Blocked and the reason.
The stage follows the agent's work.
Open a card
Click a card to open the phase's detail:
What the phase does, why, its steps, what it depends on and what it blocks, and the files it touches.
When the phase last changed, and how long it has been in progress or took.
Links that open the spec or the plan at the phase's heading.
Where the agent left what, steps or files empty, the card fills them from the plan file's own section. That text is only shown; it never changes a status.
A card whose plan file is missing says Plan file not found.
The card menu (More) has Show Details, Open Plan Section, Open Spec Section, Color and Copy Phase Title.
The agent owns the plan: you cannot change a status, a step or a title it reported.
Colors
To group related phases, choose Color in a card's menu and pick a color, or None.
The colors of the statuses, the steps chips, the stage strip and the warnings are set for the light and dark themes in , with Reset to Defaults.
Graph view
Switch the header from Board to Graph to draw the phases as a dependency graph.
The graph shows how phases depend on each other, why a phase is blocked and how big each plan section is.
Click a node to open its phase.
Notes to the agent
Send a note
Open a phase.
Write in its Notes section and click Send.
The note goes to the main session, the agent chat that started the board, the next time it reports. Subagents never see notes.
The agent may answer; its reply appears under the note as Reply from ….
Each note and reply has Copy, so you can paste it into a chat that does not use the board. Send again fills the note box with an earlier note.
Notes of phases the agent removed stay under Notes on removed phases.
A finished board keeps its notes until an agent resumes it.
Send notes to the newest session
The header says where notes go, for example Notes go to claude-code · opus · 3 min ago.
When the session that started the board was lost, for example after a restart, and another session has called the board more recently, the header offers Send notes to the newest session.
Click it to make that session the one that gets the notes.
Refresh and ask for an update
On a plain board, Refresh in the header re-reads the plan file and asks the agent's main session to bring the board up to date.
The request is delivered the next time the agent calls a board tool. The header shows Asked the agent to update, then Sent to the agent.
After 3 minutes without an answer, the header offers Copy, so you can paste the request into the agent yourself.
The header says so when the plan file cannot be read.
On a board linked to Jira, Refresh reads Jira only, and Ask the agent for an update sends the request to the agent.
A board linked to Jira
When the agent starts a board on a Jira Epic, or on a Story or Task that has children, the children become the cards.
Ask for it with /work-on-jira-issue, for example: We need to start working on DEMO-12, please read it and its children.
The board has four columns: To Do, In Progress, Ready to merge and Done.
- Done
The child's Jira status is in the Done category.
- Ready to merge
The agent finished the child, and Jira still has it in progress.
- In Progress
Jira has the child in progress, or the agent is working on it.
- To Do
Everything else.
Jira's status always wins: a child a teammate moved to Done shows in Done, whatever the agent reported.
Each card shows the child's key, its Jira summary, its Jira status, for example In Review, and the first lines of its description.
A card flags a mismatch: Not started in Jira when the agent works on a child that Jira still has in To Do, and Reopened in Jira when the agent finished a child that Jira moved back to To Do.
A phase of the agent's plan that is not a child is marked Local; it never goes to Jira.
A child that left the parent shows No longer under … and becomes local.
The board shows the first 50 children; the header says Showing the first 50 children when there are more.
The header shows when Jira was read, for example Jira read 30 s ago.
While the tab is showing, JirAI reads the children's statuses again every 2 minutes.
When Jira cannot be reached, the board keeps the last statuses and says Jira not reachable — showing statuses from ….
A board started on an issue without children stays a plain board with three columns. When that issue later gets children, the header offers … has children — show them.
Done is never automatic
Done usually means merged, or later. The agent never moves a child to Done; only you do.
Move a child to Done
On the card, click Move to Done…. Cards in Ready to merge show the button; on other cards it is in the card menu.
Confirm Move … to Done?, or choose the transition when Jira offers several. If the transition needs fields, fill them in on the transition screen.
When no Done transition is open to you, the board says No Done transition is available to you for ….
When the plan and the children differ
The agent asks you, for each gap, which you want:
A new child: click Create in Jira… on the local card. The Create tab opens with the parent, the title and the description filled in; review it and create the issue. The card then becomes a linked card.
The missing part added to an existing child as a comment, which you approve on the board.
Keep it local: nothing goes to Jira.
To join a local card to a child that already exists, choose Link to child… in the card menu.
When another Create tab has unsaved work, the board asks you to Finish or close the open Create tab first.
Approve the agent's Jira changes
The agent asks for a Jira change with jirai_start_jira_issue (move an issue to In Progress) or jirai_add_jira_comment (post a comment).
Neither tool changes Jira. Each only queues the change on the board, where you decide.
Approve or reject a change
When the agent queues a change, the board comes forward: it opens if it was closed, and its tab is selected without taking keyboard focus from your editor.
A notification says The agent is waiting for your OK on …; click Open board to go to it.
On the card, read the request, for example Agent wants to move DEMO-14 → In Progress, or Agent wants to comment on DEMO-14 with the comment shown.
Click Approve to send it, or Reject.
A change is sent at most once, and only when you click Approve. Nothing is retried automatically.
The agent learns the outcome on its next board call. It does not ask again for a rejected change unless you ask it to.
If the issue changed before you approved, for example it moved or the transition is no longer offered, the change fails with the reason.
A change asked for on one Jira site fails if you are signed in to another site, or to none, when you approve it. Nothing is sent.
Waiting changes are kept with the board, so a restart neither loses nor sends them. A board holds at most 10 waiting changes.
Every comment notifies the issue's watchers, so the agent posts one only when you ask.
On a plain board, a change to its one Jira issue is shown in the header.
Reopen a closed board
Closing the tab does not delete the board. Reopen any of the project's boards without the agent:
Choose , or find it with Find Action.
Click JirAI Virtual Boards… in the JirAI tool window title bar.
Click Open board in a notification about a waiting change.
The menu item and the button appear once the project has a board.
If you cannot see an agent's board, the agent can resume it; a resume reopens the tab.
Limitations
The board needs the IDE's MCP server and the bundled MCP Server plugin. Without them, existing boards stay listed and openable, but agents cannot update them.
Whether your agent asks your permission on each board call depends on the agent. If it asks on every report, allow the
jirai_*_virtual_*tools in that agent's own permission settings.A linked board shows a parent's direct children only.
JirAI does not notice that a child's work merged; move it to Done yourself.