llms.txt: machine-readable documentation index. Markdown version of this page is also available.

DORKAG Help

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

  1. In your agent's main chat session, do one of the following:

    • Type /use-virtual-board ($use-virtual-board in 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.

  2. Give the agent its task. From then on, it uses the board whenever it runs subagents or works through a plan with phases.

  3. 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 Settings | AI | MCP Server | Exposed Tools; 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 Settings | Tools | JirAI | Virtual Board, 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

  1. Open a phase.

  2. 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 shows the columns of your team's own Jira board for the parent's space, and each card sits in the column that holds its live Jira status. Empty columns are shown too, as on the Jira board.

  • Jira's status always wins: a child a teammate moved to Done shows in the Done column, 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. The status is not repeated when it matches the column name.

  • A card shows Agent finished when the agent finished the child and Jira does not have it done yet.

  • 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.

Where the columns come from

The header names the source, for example Columns from: DEMO board. To pick another board, click Change… and choose a board in Show Columns From, or choose Automatic.

With Automatic, JirAI uses a board located in the parent's space, preferring one you viewed recently in Jira. A board from another space is used only when you choose it.

When there is no board to copy, or Jira does not let you read it, the columns are built from the statuses instead, and the header says why, for example Columns from the space's statuses: the space has no Jira board.

  • A status that none of the columns holds gets its own extra column, for example QA — Not on board, while a card needs it.

  • When the board shows only the first 50 children, a phase whose issue is not among them goes in Status unknown.

  • A local phase goes in the first column, in the first in-progress column while the agent works on it, and keeps that column with the Agent finished badge when it is done.

Done is never automatic

Done usually means merged, or later. Nothing moves a child to Done without you: either you move it, or the agent asks to when you tell it to and you approve the move on the board. See Approve the agent's Jira changes.

Move a child to Done

  1. On the card, click Move to Done…. Cards with the Agent finished badge show the button; on other cards it is in the card menu.

  2. 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:

  1. 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.

  2. The missing part added to an existing child as a comment, which you approve on the board.

  3. 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), jirai_move_jira_issue (move an issue to any status Jira allows from where it is) or jirai_add_jira_comment (post a comment).

None of these tools changes Jira. Each only queues the change on the board, where you decide.

To move an issue, tell the agent, for example: Move DEMO-14 to In Review. It tells you the move, for example DEMO-14: In Progress → In Review, before it asks. It can ask for Done when you name it.

Approve or reject a change

  1. 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.

  2. On the card, read the request, for example Agent wants to move DEMO-14: In Progress → In Review, or Agent wants to comment on DEMO-14 with the comment shown.

  3. Click Approve to send it, or Reject.

    When the move needs fields, for example a resolution, Approve opens Jira's transition screen. Fill in the fields to send the move; cancelling the screen leaves the move waiting.

    When Jira asks for a field the IDE cannot fill, the card offers Open in Jira and Reject instead: finish the move in Jira, or reject it.

  • 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. Nothing is sent; ask the agent again.

  • An issue has at most one waiting move. To ask for another target, approve or reject the first one.

  • 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 Tools | JirAI Virtual Boards…, 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, or ask the agent to.

14 November 2026