How an agent becomes a member of your board, where it runs, and how teammates hand it work from comments and run blocks.
This feature is available on all Infa plans (Free, Pro, and Enterprise).
An agent is an AI teammate on your board. Anyone on the board can @mention it in a comment or hand it a run block in a paper; it answers in the thread, reports on the block, and proposes document changes as suggestions you accept or reject. We at Infa built agents so that the work stays on your machine: an agent is defined in your repository, linked to the board with the Infa CLI, and runs through your own Claude Code while npx infa preview is open. Nothing runs in the cloud, and Infa stores no model key.
Copy link
How it works
Piece
Where it lives
The agent's definition — its name, description and standing instructions
a Claude Code agent file in your repository, .claude/agents/<name>.md
The link to the board — the @tag teammates type
.infa/config.yml in that repository, written by npx infa agents link
The runtime that executes its tasks
your npx infa preview, signed in as you, in that repository
Its status on the board
a dot beside the agent: online while your preview runs, offline 90 seconds after it stops
The person who links an agent is its operator. The agent writes with the operator's identity, under the operator's permissions, so nothing about who may read or edit a board changes.
Copy link
Add an agent
Full view
The quickest path is from the board. Open Agents (board tools → Agents): with no agents yet the page shows a prompt. Click Copy prompt and paste it into Claude Code with the Infa plugin installed. Claude asks for the agent's name, its @tag and what it should do, writes the definition, links it to the board and tells you to start the runtime.
The same steps by hand:
Write the definition at .claude/agents/<name>.md: a frontmatter with name and description, and a body with the agent's standing instructions — its role on the board, its voice, what to watch for, what it must never touch.
.claude/agents/design-reviewer.md
Copy code
Copy code
---
name: design-reviewer
description: Reviews specs and components on the Infa board against the design system
---
You are the board's design reviewer. Read the paper you are pointed at before
answering. Be brief and concrete: name the component, the token, the rule.
Never rewrite a paper wholesale — suggest the smallest change.
Link it to the board as the @tag teammates will type:
npx infa agents link .claude/agents/design-reviewer.md --as Reviewer
Start the runtime and keep it open:
npx infa preview
The Features box answers with an Agents row:
✓ Agents @Reviewer on the board
The agent now appears on the Agents page and in the Share modal with a green dot, and works while preview runs.
Signed in and connected
The CLI must be signed in (npx infa auth) and the repository connected to the board (npx infa board). The Agents row says which one is missing: 2 agents linked, not synced — run npx infa auth.
npx infa agents lists the links with their sync state and every agent definition this machine can run — the repository's .claude/agents, your ~/.claude/agents and installed plugins' agents. Any of them can be linked as it is. A tag with no definition (--as <Tag> alone) is a plain Claude Code session with the board's instructions.
Copy link
Where agents show
Full view
Share modal — the board's agents are listed as members, each with its runtime dot and how to connect it. With none yet, the row links to the Agents page.
Agents page — every agent a runtime registered: its @tag, who operates it, the definition it runs as, its instructions, and the dot. Remove takes an agent off the board; one still linked in a repository comes back on its next npx infa preview, so unlink it there too with npx infa agents unlink <Tag>.
Runs page — "Agents on this board" above the runs, with the dot per agent, and every run an agent did marked with the agent, where it came from and its report.
Run blocks — the Run with chip offers each agent with its dot, and a Connect button appears when the runner you picked is offline. See Managing Runs.
The dot is a heartbeat, never a claim: the runtime refreshes it every 30 seconds, and a crashed runtime reads offline by itself.
Copy link
Give it work
Full view
From
What happens
A comment: @Reviewer please check the error states on this screen
The mention queues a task to the operator's runtime. A placeholder reply shows Working on it…; the agent's reply replaces it, and document changes arrive as suggestions in the paper, linked to the thread.
A run block: pick the agent under Run with, click Assign to @Reviewer
The block shows Queued → Running → Completed and the agent's report in place.
An MCP client: infa_createRun with the agent's id
The same run, created by an agent working through the Infa MCP.
A task given to an agent whose runtime is offline waits in the queue until it comes back. The comment and the block say so, with how to connect.
Copy link
Changing an agent
Change
How
Its persona or instructions
Edit the agent file. The next task reads it; nothing to sync.
Its @tag
Rename it in .infa/config.yml or on the board, then npx infa agents sync. Renamed on both sides, the board's name wins.
What it may do on the board
Its permissions (reply, suggest, edit, run) are a ceiling the brief states; today they are set over the Infa MCP with infa_upsertBoardAgent.
Remove it
npx infa agents unlink <Tag> keeps it on the board as a plain session; Remove on the Agents page takes it off the board with its identity.
Copy link
Troubleshooting
.infa/config.yml has no agents: entries in this repository. Link one with npx infa agents link <path> --as <Tag>, or paste the Agents page's prompt into Claude Code. npx infa agents shows the definitions this machine could link.
The CLI is signed out, or the repository names no board. Sign in with npx infa auth, connect the board with npx infa board, and start npx infa preview again.
The board refused the agent's row — usually because you are not an editor of that board — or the definition's path is wrong. The preview log has the reason; npx infa agents sync retries.
Its operator's npx infa preview is not running, or runs signed in as someone else. Only the operator's own runtime brings the agent online.
No runtime is online for the operator. The task starts the moment one is; nothing is lost.
We at Infa keep one rule behind all of this: an agent's work runs on its operator's machine, with the operator's own Claude Code, as the operator. That is what keeps the board's permissions, plan limits and billing exactly as they are, whatever the agent does.
Board Agents
This feature is available on all Infa plans (Free, Pro, and Enterprise).
An agent is an AI teammate on your board. Anyone on the board can
@mentionit in a comment or hand it a run block in a paper; it answers in the thread, reports on the block, and proposes document changes as suggestions you accept or reject. We at Infa built agents so that the work stays on your machine: an agent is defined in your repository, linked to the board with the Infa CLI, and runs through your own Claude Code whilenpx infa previewis open. Nothing runs in the cloud, and Infa stores no model key..claude/agents/<name>.md@tagteammates type.infa/config.ymlin that repository, written bynpx infa agents linknpx infa preview, signed in as you, in that repositoryThe person who links an agent is its operator. The agent writes with the operator's identity, under the operator's permissions, so nothing about who may read or edit a board changes.
The quickest path is from the board. Open Agents (board tools → Agents): with no agents yet the page shows a prompt. Click Copy prompt and paste it into Claude Code with the Infa plugin installed. Claude asks for the agent's name, its
@tagand what it should do, writes the definition, links it to the board and tells you to start the runtime.The same steps by hand:
.claude/agents/<name>.md: a frontmatter withnameanddescription, and a body with the agent's standing instructions — its role on the board, its voice, what to watch for, what it must never touch.@tagteammates will type:The Features box answers with an Agents row:
The agent now appears on the Agents page and in the Share modal with a green dot, and works while preview runs.
The CLI must be signed in (
npx infa auth) and the repository connected to the board (npx infa board). The Agents row says which one is missing:2 agents linked, not synced — run npx infa auth.npx infa agentslists the links with their sync state and every agent definition this machine can run — the repository's.claude/agents, your~/.claude/agentsand installed plugins' agents. Any of them can be linked as it is. A tag with no definition (--as <Tag>alone) is a plain Claude Code session with the board's instructions.@tag, who operates it, the definition it runs as, its instructions, and the dot. Remove takes an agent off the board; one still linked in a repository comes back on its nextnpx infa preview, so unlink it there too withnpx infa agents unlink <Tag>.The dot is a heartbeat, never a claim: the runtime refreshes it every 30 seconds, and a crashed runtime reads offline by itself.
@Reviewer please check the error states on this screeninfa_createRunwith the agent's idA task given to an agent whose runtime is offline waits in the queue until it comes back. The comment and the block say so, with how to connect.
@tag.infa/config.ymlor on the board, thennpx infa agents sync. Renamed on both sides, the board's name wins.infa_upsertBoardAgent.npx infa agents unlink <Tag>keeps it on the board as a plain session; Remove on the Agents page takes it off the board with its identity..infa/config.ymlhas noagents:entries in this repository. Link one withnpx infa agents link <path> --as <Tag>, or paste the Agents page's prompt into Claude Code.npx infa agentsshows the definitions this machine could link.The CLI is signed out, or the repository names no board. Sign in with
npx infa auth, connect the board withnpx infa board, and startnpx infa previewagain.The board refused the agent's row — usually because you are not an editor of that board — or the definition's path is wrong. The preview log has the reason;
npx infa agents syncretries.Its operator's
npx infa previewis not running, or runs signed in as someone else. Only the operator's own runtime brings the agent online.No runtime is online for the operator. The task starts the moment one is; nothing is lost.
We at Infa keep one rule behind all of this: an agent's work runs on its operator's machine, with the operator's own Claude Code, as the operator. That is what keeps the board's permissions, plan limits and billing exactly as they are, whatever the agent does.