agentleFS
2lab-ai2lab-ai/llmux/AGENTS.md

llmux

AGENTS.md10 starsChanged 40 days agoMITView on GitHub

Contract: .prd/01-spec.md (what) + .prd/02-architecture.md (how). Read both before non-trivial changes. This file is the single source of truth for agent/contributor rules. CLAUDE.md is a thin loader that points here — do not re-introduce dual bodies. Documentation ownership after feature work: rules/documents.md (binding). - Scheduler decisions are pure functions over snapshots. scheduler/select.rs does no IO, reads no clocks, takes (&PoolSnapshot, &SelectParams, now) and returns a Decision. All impure work (locks, CAS commit, timers) stays in scheduler/mod.rs. - State/runtime separation (herdr…

  • Commits and pushes
  • 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 repository7 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read both before non-trivial changes.

    line 4
  2. Very specific:

    All impure work (locks, CAS commit, timers) stays in scheduler/mod.rs.

    line 15
  3. Very specific:

    Never log or print raw credentials — route through proxy::logging::mask_credentials.

    line 21
  4. Very specific:

    SDK assets are build inputs: Keep bridge/claude-agent.mjs, package.json and package-lock.json in filtered source/build contexts.

    line 75
  5. Very specific:

    Push fallback: if the remote's ghs_ token is stale: git push "https://x-access-token:$(gh auth token)@github.com/2lab-ai/llmux" <ref>.

    line 83

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

llmux — agent guide (SSOT)

Contract: .prd/01-spec.md (what) + .prd/02-architecture.md (how). Read both before non-trivial changes.

This file is the single source of truth for agent/contributor rules. CLAUDE.md is a thin loader that points here — do not re-introduce dual bodies.

Documentation ownership after feature work: rules/documents.md (binding).

Architecture rules

  • Scheduler decisions are pure functions over snapshots. scheduler/select.rs does no IO, reads no clocks, takes (&PoolSnapshot, &SelectParams, now) and returns a Decision. All impure work (locks, CAS commit, timers) stays in scheduler/mod.rs.
  • State/runtime separation (herdr pattern): PoolState mutations are sync and IO-free behind a std RwLock; never hold the lock across an .await.
  • No unwrap()/expect() in production paths. Errors are typed (thiserror) and propagate; expect is acceptable only for invariants that cannot fail (e.g. poisoned-lock policy, documented at the call site) and in tests.
  • Never log or print raw credentials — route through proxy::logging::mask_credentials.

Conventions

  • Conventional commits, lowercase, no emojis, no AI co-author lines.
  • just check (fmt + clippy -D warnings + tests) must pass before every commit.
  • Config writes are read-merge-write (config::update) — never load/edit/save around a running server.
  • User-visible changes update their owning doc in the same PR — see rules/documents.md. Feature incomplete if docs-impact is skipped without an explicit N/A reason.

Runbooks

Three operational skills live in .claude/skills/ (shared mechanics in .claude/skills/_shared/cd-reference.md). Invoke by intent:

  • build (빌드) — local build → hot-deploy to the local daemon → commit → push to a feature branch (never main).
  • deploy (배포 / "배포해줘") — push to main → CI preview prerelease → refresh llmux-preview brew formula → verify → hot-deploy + restart.
  • release (릴리즈 / "릴리즈해줘") — bump version → tag v* → CI stable release → refresh llmux brew formula → verify → hot-deploy + restart → llmux status (client + server).
  • model update (모델 업데이트 / "모델 추가해줘" / "새 모델 확인해줘", even when the user names only one model) — ALWAYS sweep all four subscription providers (claude, codex, grok, gemini) for models the catalog does not yet carry; for each new model confirm (1) the exact model id, (2) API pay-as-you-go pricing (input / output / cache rates), (3) the maximum context window, each with its source URL and date; then add the rows to src/catalog.rs + src/pricing.rs, move the family aliases (sonnet / opus / fable / sol / terra / luna / astra / grok / gemini / argon) to the newest generation, and update docs/models.md in the same PR. The sweep runs only when the user asks — never as a background poll. (Standing instruction 2026-10-06.)

Scheduler design history (not rules): .prd/06-scheduler-current.md, .prd/07-scheduler-research.md.

Load-bearing facts (don't relearn the hard way)

  • A stable release requires a version bump. The release workflow fails if the v* tag ≠ Cargo.toml version, and the last version's tag already exists. Pick the next version with the user.
  • Preview publication includes the tap bump. preview.yml directly renders and pushes the preview formula/cask; failures fail the publish job. As of 2026-10-08 the tap’s llmux jobs are schedule-only; manual dispatch is for Dbotter. Immediate stable delivery uses the shared reference’s reviewed two-file template fallback; preview recovery reruns the failed publish job. See the shared CD reference for exact verification and docs-only [skip ci] handling.
  • Frontend is separate from backend. run launches Claude Code; run --codex launches Codex. Claude on Responses must use the official SDK with selected-account isolation, external client-tool execution and shared scheduler/error semantics. Preserve endpoint origin independently of model/provider in Activity and native views.
  • SDK assets are build inputs. Keep bridge/claude-agent.mjs, package.json and package-lock.json in filtered source/build contexts. Claude-through-Codex needs Node.js 18+ and npm on the daemon; normal binaries lazily bootstrap without a checkout. Bridge changes require locked npm installation and just check-bridge in addition to the required Rust gate. See bridge contracts.
  • Local hot-deploy gotcha. The Cellar binary is read-only (r-xr-xr-x), so cp over it fails — rm -f "$(readlink -f /opt/homebrew/bin/llmux)" first, then cp, chmod 755, then llmux restart. A later brew upgrade overwrites a hot-deployed dev binary.
  • Push fallback if the remote's ghs_ token is stale: git push "https://x-access-token:$(gh auth token)@github.com/2lab-ai/llmux" <ref>.
  • Sanitize Gate (.github/workflows/sanitize-gate.yml) scans every published commit — files, messages, author lines, branch and tag names — for private host names and other companies' names and domains. The patterns live only in the SANITIZE_PATTERNS_SHARED secret, which 2lab-ai/soma-work holds with the same value; scripts/sanitize-scan.sh is a byte-identical copy of soma-work's. Write "a shared host" or "the owner's Mac" instead of a machine name, and commit with a configured user.email (git's default user@hostname puts the host name in the author line). The history was rewritten on 2026-11-12, so nothing is exempt: a hit is fixed by rewriting the commit, never by listing it.
  • The /api/oauth/usage endpoint returns percentages (0–100), not fractions — each evidence source has a fixed scale (see src/scheduler/usage.rs).

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.