docs/generated/agents.mdgenerated from code

How Agentflare works · 3 min read

Agents and access

Agents under their own names, and who may do what on which files.

On this page
Give an agent its own nameWhat a name limits, and what it doesn'tAccessAgents and people see each otherTools that work with af

An agent is an AI coding program working beside you. In af it edits main live, like a person, under its own name and key. Every save says who made it.

Give an agent its own name

With the af plugin for Claude Code or OpenCode, each agent session gets a name of its own by itself: the Agent guide says how to set one up. For any other agent, make it a name:

terminalon main
1agentflare key new --alias agent-0

This makes a key for agent-0 and lets it edit, message, and approve on every file. Start the agent with LVCS_PEER=agent-0 set, and the agentflare commands it runs act as agent-0. To limit those commands to some files, add --paths:

terminalon main
1agentflare key new --alias agent-0 --paths 'src/**'

What a name limits, and what it doesn't

A name's access limits what af takes from that name: an agentflare write outside its --paths is refused. It is not a sandbox. The agent runs on your machine as you, and can read and write every file there. A file it writes straight to disk, rather than through the plugin or agentflare write, is saved as your machine's default peer, not as the agent.

To really limit an agent, run it on a machine of its own, a VM or a container, that joins the project as its own peer (Peer to peer), and grant that peer only what it needs.

Access

The owner, who made the project, decides who may do what, and on which files. Each kind of access is a word you grant:

AccessWhat it lets someone do
readRead the files.
writeEdit them.
approveApprove saves to protected files, like lvcs.toml.
delegateLet others in, within their own access.
messageSend messages and mentions; a plugin can add words like this one.

To let someone in from another machine, they run agentflare join <project> there and send you the peer= id it prints. Grant that id what they need, with a name to show it by; from then on the name works too:

terminalon main
1agentflare grant <their peer id> write --paths 'src/**' --alias maya2agentflare grant maya approve3agentflare grant anyone read          # make the project public

agentflare status lists your own access. agentflare revoke <grant> takes access back, and every machine honors it once it hears. A grant made with --ttl ends by itself unless the daemon that made it keeps renewing it, so a machine that is offline when you revoke still stops honoring the grant within one window.

Agents and people see each other

As they type, everyone sees which files and lines the others are on. Before an agent edits lines someone else is on, the af plugins for Claude Code and OpenCode announce the lines it's about to change, so the others hear before anything is written, not an hour later at a merge. If two of them do edit the same line, both edits survive.

When a check fails on lines an agent changed, the failure goes to that agent, which reads it with agentflare notify and fixes it. Checks has more.

Tools that work with af

Claude Code and OpenCode have af plugins, and there is a VS Code extension. Any other tool that can run a shell command works through agentflare. The Agent guide says how to set up each, and what af teaches your agent.