Give an agent a monorepo#

Your coding agent must change acme/web and acme/docs together. You do not want to start a session for each repository, and you do not want to explain to the agent which repository is where.

Start one session on the monorepo. Its token works on the monorepo and on every member, and its agents.md tells the agent about all members.

1. Start a session on the monorepo#

1. Open the monorepo, then the Agents tab.
2. Pick a profile, write the Purpose, and click Start session.
3. Copy the token. The page shows it one time only.

Connect your coding agent shows the form and the profiles.

The token works on the monorepo and on each member:

• On each member, the agent has your own role there, capped by its profile.
• A member that is added later is in. A member that is removed drops out at the next request.
• On any other repository, the token is refused.

2. Give the agent the context#

Tell the agent to read this URL before it starts:

https://gitflare.t-zlak97.workers.dev/acme/platform/agents.md

For a monorepo, this file has a Monorepo section:

• Each member, with its folder, its visibility and its default branch.
• A link to the agents.md of each member.
• The command that clones the monorepo and every member.
• The MCP tools that search across the members.

3. Let the agent clone the members#

With MCP, the agent calls list_monorepo_members. The answer has each member and the git commands that make the checkout. The agent sends its token on each git command, the same as in Connect your coding agent.

4. Let the agent search#

The agent searches all members in one call:

What	MCP tool	REST route
Issues and pull requests	search_monorepo_items	GET /api/v1/repos/acme/platform/members/search/issues?q=...
Code on each default branch	search_monorepo_code	GET /api/v1/repos/acme/platform/members/search/code?q=...

The code search has caps on the bytes that it reads and on the size of the result. When it stops at a cap, the answer says that the result is cut.

Done#

Your agent has one token and one agents.md for the whole monorepo. It knows each folder, and it finds code and issues in every member.

What the agent can do in a member#

• It pushes only to agent/<session>/... branches, in each member. It never pushes to a default branch.
• It opens one monorepo pull request with a part in each member that it changed. A person merges it. See Change several members in one pull request.

Factory agents on a monorepo#

Turn on a factory agent for the monorepo, the same as for any repository. Its issues are the monorepo's own issues.

• The agents that search (for example triage and investigate) also get list_members, list_member_files, read_member_file and search_member_code. They read each member at its default branch.
• search_items finds the issues and pull requests of every member too. Held items stay hidden.
• A run that changes code checks out every member inside the monorepo's checkout, as src monorepo clone lays them out.
• Auto PR opens one monorepo pull request, with a part in each member that it changed. It pushes only factory/issue-<n> in each member. Each part waits in screening, and a person merges.
• Custom agents get the members in their checkout, but not the member tools and not open_monorepo_pr.

A scoped token instead#

A scoped token on the monorepo also covers its members, with the actions of the token only:

TOKEN=$(src token create -R acme/platform --write --expires 2h)