docs: improve AGENTS.md for agent/sandbox environments#21997
Open
mazze93 wants to merge 4 commits intoHomebrew:mainfrom
Open
docs: improve AGENTS.md for agent/sandbox environments#21997mazze93 wants to merge 4 commits intoHomebrew:mainfrom
mazze93 wants to merge 4 commits intoHomebrew:mainfrom
Conversation
Documents how to configure a writable cache directory in sandboxed environments (e.g. OpenAI Codex) to avoid permission errors when running the test suite. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Fix ambiguous intro sentence ("before prompting for input")
- Fix double space in `--online --changed` example
- Add missing repo structure entries: cmd/, dev-cmd/, test/, sorbet/
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ls after gem changes unless stubs are regenerated. The --update vs --update-all distinction prevents agents from unnecessarily rebuilding everything on a DSL-only change. Sandbox setup (lines 28–34) — Rewritten as explicit numbered steps. The original buried the HOMEBREW_CACHE path structure in prose; the corrected tmp/cache/ (not tmp/cache/api/) export path also fixes a subtle bug in the original where the exported var pointed one level too deep. Completions/manpages trigger (lines 48, 59) — Changed "don't edit directly" to also say when to regenerate. Without this, an agent adding a flag to a command would correctly update the Ruby but silently skip the generated files. HOMEBREW_BREW_FILE clarification (line 71) — Added a concrete usage example (safe_system HOMEBREW_BREW_FILE, "install", name) and made explicit that ./bin/brew is for the terminal only. The old wording was ambiguous enough that an agent might apply the rule in the wrong direction. Commit conventions (line 73) — Grounded in observed history (livecheck:, sorbet:, tests:, docs:). Includes the automated tooling carve-out so agents don't try to reformat dependency bumps.
MikeMcQuaid
reviewed
Apr 13, 2026
Member
MikeMcQuaid
left a comment
MikeMcQuaid
left a comment
There was a problem hiding this comment.
Please reduce the scope of this, most of this is random rewording.
| # Agent Instructions for Homebrew/brew | ||
|
|
||
| Most importantly, run `./bin/brew lgtm` to verify any file edits before prompting for input to run all style checks and tests. | ||
| Most importantly, run `./bin/brew lgtm` to verify any file edits before prompting the user, to run all style checks and tests. |
Member
There was a problem hiding this comment.
Don't change random words like this.
|
|
||
| 1. Copy the API cache: `cp -r "$(./bin/brew --cache)/api/" tmp/cache/api/` | ||
| 2. Export the writable path: `export HOMEBREW_CACHE="$(pwd)/tmp/cache/"` | ||
| 3. Then run `./bin/brew tests` as normal. |
Member
There was a problem hiding this comment.
This should already be handled by brew tests. Can you please verify and submit a PR to do that if not?
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
2 participants
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.
Adds sandbox setup instructions and improves existing content for AI agents working in this repository.
Changes
### Sandbox Setupsection explaining how to configure a writableHOMEBREW_CACHEin sandboxed environments (e.g. OpenAI Codex) to avoid permission errors when running the test suite--online --changedcommand example## Repository Structurewith missing entries:cmd/,dev-cmd/,test/,sorbet/brew lgtm(style, typechecking and tests) with your changes locally? — not applicable (no Ruby/Bash changes)