vibe-island
AGENTS.md4 starsChanged 5 months agoMITView on GitHub
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository5 other files it gives its agents.
- docs/claude.mdCLAUDE.md
- docs/llms.txtllms.txt
- codexbarSkill
- qa-testSkill
- release-codexbarSkill
The file
We split this AGENTS.md into the rules it gives an agent
10 rules. About 0 are common, 4 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 20
Add/extend XCTest cases under Tests/CodexBarTests/*Tests.swift (FeatureNameTests with test_caseDescription methods).
- Very specific: line 23
Always run make test before handoff.
- Very specific: line 24
After any code change, run make check and fix all reported format/lint issues before handoff.
- Distinctive: line 25
Prefer CLI/focused tests over app-bundle live tests when behavior can be verified without relaunching CodexBar.
- Very specific: line 26
Never run tests/checks or ad-hoc validation that can display macOS Keychain prompts.
- Distinctive: line 30
Commit messages: short imperative clauses (e.g., “Improve usage probe”, “Fix icon dimming”).
- Distinctive: line 34
Use the provided scripts and package manager (SwiftPM).
- Very specific: line 40
Run ./Scripts/compile_and_run.sh only when UI/runtime behavior needs bundle-level validation.
- Very specific: line 45
Prefer modern SwiftUI/Observation macros: use @Observable models with @State ownership and @Bindable in views.
- Distinctive: line 47
Keep provider data siloed: when rendering usage or account info for a provider (Claude vs Codex), never display identity/plan fields …
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Repository Guidelines
Project Structure & Modules
Sources/CodexBar: Swift 6 menu bar app (usage/credits probes, icon renderer, settings). Keep changes small and reuse existing helpers.Tests/CodexBarTests: XCTest coverage for usage parsing, status probes, icon patterns; mirror new logic with focused tests.Scripts: build/package helpers (package_app.sh,sign-and-notarize.sh,make_appcast.sh,build_icon.sh,compile_and_run.sh). Release wrappers callScripts/mac-release, which resolvesMAC_RELEASE_TOOLor the sharedagent-scriptscheckout.docs: release notes and process (docs/RELEASING.md, screenshots). Root-level zips/appcast are generated artifacts—avoid editing except during releases.
Build, Test, Run
- Dev loop:
./Scripts/compile_and_run.shkills old instances, builds, packages, relaunchesVibeisland.app, and confirms it stays running; add--testfor the sharded full suite. - Quick build/test:
swift build(debug) orswift build -c release;make testfor the sharded full suite. - Package locally: from this repository, run
./Scripts/package_app.shto refreshVibeisland.app, then restart withpkill -x CodexBar || true; open -n ./Vibeisland.app. - Release flow:
./Scripts/release.sh; app metadata lives in.mac-release.env, repo build/signing stays inScripts/sign-and-notarize.sh, and validation steps live indocs/RELEASING.md.
Coding Style & Naming
- Enforce SwiftFormat/SwiftLint: run
swiftformat Sources Testsandswiftlint --strict. 4-space indent, 120-char lines, explicitselfis intentional—do not remove. - Favor small, typed structs/enums; maintain existing
MARKorganization. Use descriptive symbols; match current commit tone.
Testing Guidelines
- Add/extend XCTest cases under
Tests/CodexBarTests/*Tests.swift(FeatureNameTestswithtest_caseDescriptionmethods). - Swift Testing: prefer backticked sentence names; no camelCase.
- Model names in tests/code: released models or clearly fictitious names only; never expose unreleased names.
- Always run
make testbefore handoff; add focusedswift test --filter ...runs for parser/provider fixes when possible. - After any code change, run
make checkand fix all reported format/lint issues before handoff. - Prefer CLI/focused tests over app-bundle live tests when behavior can be verified without relaunching CodexBar.
- Never run tests/checks or ad-hoc validation that can display macOS Keychain prompts. Live provider probes, browser-cookie imports,
codexbar usageagainst real accounts, and real SecItem reads must be explicitly requested; otherwise use parser tests, stubs, test stores, orKeychainNoUIQuery. - macOS CI is brittle around headless AppKit status/menu tests. Prefer covering menu behavior through stable state/model seams (
MenuDescriptor,ProvidersPane,CodexAccountsSectionState, etc.) instead of constructing liveNSStatusBar/NSMenuflows unless the AppKit wiring itself is the thing under test.
Commit & PR Guidelines
- Commit messages: short imperative clauses (e.g., “Improve usage probe”, “Fix icon dimming”); keep commits scoped.
- PRs/patches should list summary, commands run, screenshots/GIFs for UI changes, and linked issue/reference when relevant.
Agent Notes
- Use the provided scripts and package manager (SwiftPM); avoid adding dependencies or tooling without confirmation.
- For image generation, use Codex's built-in image generation tool by default; do not require or ask for an
OPENAI_API_KEYunless the user explicitly requests CLI/API model controls. - Menu bar automation: capture the target screen first and verify the CodexBar icon is visibly onscreen. Reject
click-extrasuccess when coordinates fall outside display bounds; hidden menu extras are not click proof. - Validate UI/runtime behavior against the freshly built bundle; restart via the pkill+open command above to avoid running stale binaries.
- To guarantee the right bundle is running after a rebuild, run from this repository:
pkill -x CodexBar || true; open -n ./Vibeisland.app. - For CLI-testable provider/parser/settings behavior, use CLI/focused tests instead of
Scripts/package_app.shor./Scripts/compile_and_run.sh. - Run
./Scripts/compile_and_run.shonly when UI/runtime behavior needs bundle-level validation; it builds, tests, packages, relaunches, and verifies the app stays running. - Widget/Tahoe UI issues: use Parallels macOS VM plus screenshots/clicks for autonomous verification.
- Release script: keep it in the foreground; do not background it—wait until it finishes.
- Sparkle release key: use
.mac-release.envMAC_RELEASE_SIGNING_KEY_FILE, the legacyAGCY8w5vHirVfGGDGc8Szc5iuOqupZSh9pMj/Qs67XI=key. Do not usesparkle-private-key-KEEP-SECURE.txt; that is VibeTunnel's mismatched key. - Swift concurrency: treat sibling
async lettasks as a review red flag when one child is required and another is optional/best-effort. Prefer sequential awaits or a drainedwithThrowingTaskGroupthat surfaces required failures and explicitly contains optional failures; crash stacks mentioningswift_task_deallocorasyncLet_finish_after_task_completionshould trigger an audit of nearbyasync letusage. - Prefer modern SwiftUI/Observation macros: use
@Observablemodels with@Stateownership and@Bindablein views; avoidObservableObject,@ObservedObject, and@StateObject. - Favor modern macOS 15+ APIs over legacy/deprecated counterparts when refactoring (Observation, new display link APIs, updated menu item styling, etc.).
- Keep provider data siloed: when rendering usage or account info for a provider (Claude vs Codex), never display identity/plan fields sourced from a different provider.***
- Claude CLI status line is custom + user-configurable; never rely on it for usage parsing.
- Cookie imports: default Chrome-only when possible to avoid other browser prompts; override via browser list when needed.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

