# Board Agents

> How an agent becomes a member of your board, where it runs, and how teammates hand it work from comments and run blocks.

Source: https://infa.ai/docs/runners-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 `@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 `infa preview` is open. Nothing runs in the cloud, and Infa stores no model key.

**No account, or a model on your own machine?**
A [local agent](https://infa.ai/docs/infa-cli-local-agents) runs on a model served from your computer (Ollama, vLLM) and works on the local board, with no account and no internet connection.

## 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 `infa agents link` |
| The runtime that executes its tasks | your `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.

## Add an agent

![The Agents page with no agents yet: the setup prompt to paste into Claude Code, a Copy prompt button, and the two commands by hand](https://infa.ai/docs/screenshots/agents/agents-page-empty.webp)

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:

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

```md title=".claude/agents/design-reviewer.md"
---
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.
```

2. Link it to the board as the `@tag` teammates will type:

```bash
infa agents link .claude/agents/design-reviewer.md --as Reviewer
```

3. Start the runtime and keep it open:

```bash
infa preview
```

The Features box answers with an **Agents** row:

```text
✓ 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 (`infa auth`) and the repository connected to the board (`infa board`). The Agents row says which one is missing: `2 agents linked, not synced — run infa auth`.

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

## Where agents show

![The Share modal with an Agents row among the board's members, reading Add an agent](https://infa.ai/docs/screenshots/agents/share-modal-agents.webp)

- **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 `infa preview`, so unlink it there too with `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](https://infa.ai/docs/runners-runs).

The dot is a heartbeat, never a claim: the runtime refreshes it every 30 seconds, and a crashed runtime reads offline by itself.

## Give it work

![A draft run block in a paper, expanded: the prompt, the Branch chip, the runner reading offline with the instruction to start infa preview, and the Run and Connect buttons](https://infa.ai/docs/screenshots/agents/run-block-draft.webp)

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

## 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 `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 | `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. |

## Troubleshooting

**The preview banner says 'none linked**
`.infa/config.yml` has no `agents:` entries in this repository. Link one with `infa agents link <path> --as <Tag>`, or paste the Agents page's prompt into Claude Code. `infa agents` shows the definitions this machine could link.

**The banner says 'linked, not synced — run infa auth' (or 'infa board')**
The CLI is signed out, or the repository names no board. Sign in with `infa auth`, connect the board with `infa board`, and start `infa preview` again.

**The banner says '1 link failed**
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; `infa agents sync` retries.

**The agent is offline on the board**
Its operator's `infa preview` is not running, or runs signed in as someone else. Only the operator's own runtime brings the agent online.

**A task stays queued**
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.

## Related topics

- [Claude Code Agent Runners](https://infa.ai/docs/runners)
- [Managing Runs](https://infa.ai/docs/runners-runs)
- [Claude Code Plugin](https://infa.ai/docs/claude-plugin)
- [Local Agents](https://infa.ai/docs/infa-cli-local-agents)
