docs: bring the README current and document what it actually takes to run this#18
Merged
Conversation
… run this Stale: github-plugin v0.2.0 -> v0.3.0, pr-reviewer v0.5.0 -> v0.17.0 (twelve releases behind), base 0.106.0 -> 0.108.0, and it described a repo webhook plus an authenticated `gh` when the reviewer is a GitHub App minting installation tokens. Version claims are now checked against the manifest and Dockerfile rather than written from memory. Adds the section that was missing entirely: what it actually takes to run this, ordered so the two requirements that fail SILENTLY come first. The GitHub App section carries a permissions table derived from the API calls the plugin really makes, and the webhook events — an App subscribed only to `pull_request` accepts the summon feature and then never delivers a command. Correct code, no event, no error. That cost a day; it is now documented with the health endpoint that diagnoses it in one request. The inference section documents both failures we hit for real: a 32768-token TOTAL ceiling (prompt plus output) that exhausted the panel on every large diff, and a 12000 TPM free tier that rejected a single finder. Five parallel finders at ~37k tokens each is the requirement; nine LLM steps and 5-9 minutes is the cost. Writes down two judgement calls: don't skip to hard branch protection (require that a verdict EXISTS, not that it approves — this panel has produced a twice-confirmed hallucinated blocker), and self-hosting is the supported path for other orgs, because multi-tenant hosting is a different product. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The README was materially wrong in ways that would waste a newcomer's day.
Stale facts, now corrected
ghauthenticated"Version claims are now checked against
protoagent.bundle.yamland theDockerfilerather than written from memory.The part that was missing entirely: what it takes to run this
A Requirements section covering the four things that must be true before a single review runs — ordered so the two that fail silently come first.
1. The GitHub App. Permissions table derived from the API calls the plugin actually makes (
/pulls,/contents,/check-runs,/issues,/collaborators, graphql), and — critically — the webhook events:That cost us a day. It's now called out with the health endpoint that diagnoses it in one request.
2. Inference with enough context. The panel is five parallel finders at ~37k tokens each. Documented: context ≥ 64k with headroom, no aggressive TPM cap, and the two failures we actually hit — a 32,768-token total ceiling (prompt plus output) that exhausted the panel on every large diff, and a 12,000 TPM free tier that rejected a single finder. Plus the honest cost: nine LLM steps, 5–9 minutes, ~$0.12–0.15 a review hosted.
3. Host tooling.
git,gh,clawpatch— and that a missingclawpatchdegrades rather than fails.4. Config. The knobs an operator actually reaches for, noting they resolve live now.
Two judgement calls written down
Don't skip to hard branch protection. Requiring the QA review to approve before merge sounds like the end state and isn't — this panel produced a twice-confirmed hallucinated blocker where the correct outcome was an adjudicated merge past it. If you want a merge-time guard, require that a verdict exists, not that it approves.
Other orgs: self-hosting is documented as the supported path. A multi-tenant hosted App is a different product with different problems (per-org secrets, budget isolation, noisy neighbours on a shared panel), and saying so beats leaving it implied.
Also new
What the deterministic machinery does that prompts can't (confinement, grounding, convergence, dispositions, fail-closed exhaustion, guard telemetry), the on-demand command surface, and a callout that the config volume is seed-once — which is why the operator state has env fallbacks.
🤖 Generated with Claude Code