agentleFS
Richard-Yang0130Richard-Yang0130/vibe-island/AGENTS.md

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.

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
  1. Very specific:

    Add/extend XCTest cases under Tests/CodexBarTests/*Tests.swift (FeatureNameTests with test_caseDescription methods).

    line 20
  2. Very specific:

    Always run make test before handoff.

    line 23
  3. Very specific:

    After any code change, run make check and fix all reported format/lint issues before handoff.

    line 24
  4. Distinctive:

    Prefer CLI/focused tests over app-bundle live tests when behavior can be verified without relaunching CodexBar.

    line 25
  5. Very specific:

    Never run tests/checks or ad-hoc validation that can display macOS Keychain prompts.

    line 26
  6. Distinctive:

    Commit messages: short imperative clauses (e.g., “Improve usage probe”, “Fix icon dimming”).

    line 30
  7. Distinctive:

    Use the provided scripts and package manager (SwiftPM).

    line 34
  8. Very specific:

    Run ./Scripts/compile_and_run.sh only when UI/runtime behavior needs bundle-level validation.

    line 40
  9. Very specific:

    Prefer modern SwiftUI/Observation macros: use @Observable models with @State ownership and @Bindable in views.

    line 45
  10. Distinctive:

    Keep provider data siloed: when rendering usage or account info for a provider (Claude vs Codex), never display identity/plan fields …

    line 47

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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 call Scripts/mac-release, which resolves MAC_RELEASE_TOOL or the shared agent-scripts checkout.
  • 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.sh kills old instances, builds, packages, relaunches Vibeisland.app, and confirms it stays running; add --test for the sharded full suite.
  • Quick build/test: swift build (debug) or swift build -c release; make test for the sharded full suite.
  • Package locally: from this repository, run ./Scripts/package_app.sh to refresh Vibeisland.app, then restart with pkill -x CodexBar || true; open -n ./Vibeisland.app.
  • Release flow: ./Scripts/release.sh; app metadata lives in .mac-release.env, repo build/signing stays in Scripts/sign-and-notarize.sh, and validation steps live in docs/RELEASING.md.

Coding Style & Naming

  • Enforce SwiftFormat/SwiftLint: run swiftformat Sources Tests and swiftlint --strict. 4-space indent, 120-char lines, explicit self is intentional—do not remove.
  • Favor small, typed structs/enums; maintain existing MARK organization. Use descriptive symbols; match current commit tone.

Testing Guidelines

  • Add/extend XCTest cases under Tests/CodexBarTests/*Tests.swift (FeatureNameTests with test_caseDescription methods).
  • 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 test before handoff; add focused swift test --filter ... runs for parser/provider fixes when possible.
  • After any code change, run make check and 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 usage against real accounts, and real SecItem reads must be explicitly requested; otherwise use parser tests, stubs, test stores, or KeychainNoUIQuery.
  • 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 live NSStatusBar/NSMenu flows 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_KEY unless 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-extra success 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.sh or ./Scripts/compile_and_run.sh.
  • Run ./Scripts/compile_and_run.sh only 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.env MAC_RELEASE_SIGNING_KEY_FILE, the legacy AGCY8w5vHirVfGGDGc8Szc5iuOqupZSh9pMj/Qs67XI= key. Do not use sparkle-private-key-KEEP-SECURE.txt; that is VibeTunnel's mismatched key.
  • Swift concurrency: treat sibling async let tasks as a review red flag when one child is required and another is optional/best-effort. Prefer sequential awaits or a drained withThrowingTaskGroup that surfaces required failures and explicitly contains optional failures; crash stacks mentioning swift_task_dealloc or asyncLet_finish_after_task_completion should trigger an audit of nearby async let usage.
  • Prefer modern SwiftUI/Observation macros: use @Observable models with @State ownership and @Bindable in views; avoid ObservableObject, @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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.