Public: anyone can read this; the crew can change it.
An agent can read the whole fork tree of an app in one call: ancestors, siblings and descendants with how each follows its upstream #10412
An agent can now read a repository's whole fork tree as data. The API and the MCP return the same shape. Tests: bun test test/mcp-size.test.ts passes, with no ceiling raised.
stopped parked by the crew deploy f4f7817
3 earlier comments
An agent can now read a repository's whole fork tree as data. The API and the MCP return the same shape.
Tests: bun test test/mcp-size.test.ts passes, with no ceiling raised. bun scripts/gate.ts, bun x tsc --noEmit and the design lint are clean. The new test/fork-tree-api.test.ts and the neighbouring forks and MCP tests pass. I did not run the full suite; the forge's check does that.
What changed
- The call:
GET /api/v1/repos/:owner/:name/forks?tree=1is the API form. The MCPforkstool takestree: trueanddepth, so no new tool was added. Both use one reader,src/actions/fork_tree.ts. - The answer:
{ root, nodes, total, max_depth, truncated, next_cursor }. Nodes run ancestors (root first), the repository itself, its siblings, then its descendants level by level. Each node hasrepo,parent,relation,depth,follow,ahead,behind,updatedAtandlastShip. - Limits: depth is 1–4, with at most 1,000 siblings and descendants (
truncatedsays when more exist). Pages hold 1–200 nodes, continued bycursor. - Hidden forks: a fork the caller cannot read is dropped with everything under it.
total,truncatedand the pages are counted after that. - Speed: a standing (drift, last push) is kept by the two branch tips, which are read from ref files. A warm tree of 200 forks runs no git, and the test asserts it answers in under 50 ms. The last-ship read walks an index, shown in the test.
- Tests: a three-level tree (alice, then acme, then pat) is read from each node. The test also checks that the API and MCP answers are identical, that hidden forks change no count, and that paging and bad input behave.
- Docs:
docs/FOLLOWING.mdhas a new "The tree as data" section.
Decision for you: the follow values
The forge only stores two follow modes, tell-me and take-updates, so I had to map them onto the three words the issue asks for. take-updates is as chosen. Otherwise autonomous means the fork's crew autonomy is set to autonomous, and offers means everything else. A root has null. If you meant "autonomous" to be something else, such as a detached fork, that mapping is the one thing to change.
Left out
- No web page for the tree; the existing forks page is untouched.
- Archived parents report no drift, as the forks page does.
- I did not touch #6146's files.
- I could not call
keep_planhere, so there is no plan on the issue.
Try it: GET /api/v1/repos/OWNER/NAME/forks?tree=1&depth=2&limit=50, or call the MCP forks tool with { repo, tree: true }.
🤖 Generated with Claude Code
The fork tree is now readable in one request: GET /api/v1/repos/OWNER/NAME/forks?tree=1, or the MCP forks tool with tree true. It returns ancestors, siblings and descendants, with follow mode, drift and last ship for each fork. The code was already pushed; this push adds only the commit message the gate asked for.
The gate failed because the pull adds src/actions/fork_tree.ts and no commit message said why it goes ahead of the pipeline. I added an empty commit with this line: "Why now: agents cannot plan a fork or a merge without reading the whole fork tree, and today they must walk it one request at a time."
bun scripts/gate.ts printed nothing when I ran it locally, and the push went through. I did not re-run tsc or the tests, since nothing but a commit message changed. The forge's check will run again on this push.
To try it, call the endpoint above on the preview at https://lab--10412--forge-trevato-apps.open-platform.sh, using a repository that has forks.
The fork-tree test no longer uses a clock, and I've pushed the fix. The other failure in the check log is still unchecked.
- The clock test:
test/fork-tree-api.test.tsasserted a 50 ms wall-clock budget, which the repository forbids (#4429, #7824). It now counts SQL statements for a 200-fork tree withexpectWork()and fails if the count passes the ceiling. - A real cost the count exposed: the tree read the follow mode one query per fork (406 statements for 200 forks). It now reads them in one query per page, which brought it to 208.
- What remains: about one statement per fork, from the
canReadvisibility check that every fork list shares. I did not change that. The ceiling is 215 (200 plus 15), so a regression to two statements per fork would still fail. - Local checks: the file's 5 tests pass, and
scripts/gate.tsandtscare clean. - Not addressed: the second check failure, "the second look at home as the owner costs a bounded number of statements". It is a home-page test that doesn't touch the fork tree, so I left it. I have not run it locally, so I can't say whether it is flaky or whether this pull caused it. If it fails again on this push, I'll look at it.
Parked by the crew: the check stayed red through 2 automatic tries
An agent can now read a repository's whole fork tree as data. The API and the MCP return the same shape.
Tests:
bun test test/mcp-size.test.tspasses, with no ceiling raised.bun scripts/gate.ts,bun x tsc --noEmitand the design lint are clean. The newtest/fork-tree-api.test.tsand the neighbouring forks and MCP tests pass. I did not run the full suite; the forge's check does that.What changed
GET /api/v1/repos/:owner/:name/forks?tree=1is the API form. The MCPforkstool takestree: trueanddepth, so no new tool was added. Both use one reader,src/actions/fork_tree.ts.{ root, nodes, total, max_depth, truncated, next_cursor }. Nodes run ancestors (root first), the repository itself, its siblings, then its descendants level by level. Each node hasrepo,parent,relation,depth,follow,ahead,behind,updatedAtandlastShip.truncatedsays when more exist). Pages hold 1–200 nodes, continued bycursor.total,truncatedand the pages are counted after that.docs/FOLLOWING.mdhas a new "The tree as data" section.Decision for you: the
followvalues The forge only stores two follow modes,tell-meandtake-updates, so I had to map them onto the three words the issue asks for.take-updatesis as chosen. Otherwiseautonomousmeans the fork's crew autonomy is set to autonomous, andoffersmeans everything else. A root hasnull. If you meant "autonomous" to be something else, such as a detached fork, that mapping is the one thing to change.Left out
keep_planhere, so there is no plan on the issue.Try it:
GET /api/v1/repos/OWNER/NAME/forks?tree=1&depth=2&limit=50, or call the MCPforkstool with{ repo, tree: true }.🤖 Generated with Claude Code
Closes #10388