Run several agents on one repository

Agents each work inside their own agent/<name>/** lane scope, so they cannot interleave commits. Coordination is about not duplicating or fighting over the same files.

Declaring intent

tovio agent intent declare --token <token-id> 'src/parser/**' --ttl 3600tovio agent intent check src/parser/lexer.rs src/parser/ast.rstovio agent intent list

Three details that trip people up:

• The globs are positional arguments, listed after the flags. There is no --paths.
• --ttl is a number of seconds, defaulting to 3600. --ttl 1h is a usage error, not one hour.
• intent check takes concrete paths you are about to touch, not globs. It answers "is another agent working here?".

Intent is scoped to the token

A declared glob must sit inside the declaring token's own path scope. An agent cannot advertise intent on paths it could not write — otherwise the signal would mislead everyone reading it. A glob that begins with a wildcard (**/x, *.env) has no boundary the engine can check, so it is refused fail-closed; declare a concrete prefix instead.

Advisory, with one exception

Intent does not lock anything. It advertises what an agent is working on so others can steer around it. The single non-advisory outcome is a soft block: if another agent holds an advisory --lease over the same paths and the repository's coordination policy requires blocking, the declaration is rolled back and fails. An agent that means it can pass --force.

--lease itself only takes effect through a Forge's coordination registry. With no Forge configured, the command tells you the flag had no effect rather than silently pretending otherwise.

What intent check can and cannot see

intent check reads the declarations recorded in this working copy. Cross-machine overlap is detected at declare time, when the declaration is registered with a configured Forge and compared against other agents' live sessions, and it surfaces to MCP clients as coordination warnings on connect. So intent check is a good local guard and a poor fleet-wide one — do not treat a clean result as proof that nobody else is in that directory.

A Forge outage never fails a declare. The local declaration stands and intent check keeps working.

Why not locks

Locks are for content that genuinely cannot be merged, like binary assets. Source code merges, and blocking agents on each other converts a merge into a queue.

When work does collide

You get a conflict object. Your tree stays buildable, and tovio conflicts lists it — the same mechanism as human conflicts, with the same resolution path.

Keeping up

tovio sync --watch

Reviewing a fleet

tovio log --entity agenttovio agent listtovio agent intent list

One session is one admitted grant

Where hosted plans meter agent usage, the unit is the admitted session grant, not wall-clock time. A fleet that reconnects for every small task therefore costs more than the same fleet holding a session open across tasks — worth knowing before you design the orchestration loop around reconnecting.