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.
- CLAUDE.mdCLAUDE.md
- agent-loopSkill
- agent-resolveSkill
- agent-triageSkill
- buildSkill
- deploySkill
- releaseSkill
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
- Distinctive: line 4
Read both before non-trivial changes.
- Very specific: line 15
All impure work (locks, CAS commit, timers) stays in scheduler/mod.rs.
- Very specific: line 21
Never log or print raw credentials — route through proxy::logging::mask_credentials.
- Very specific: line 75
SDK assets are build inputs: Keep bridge/claude-agent.mjs, package.json and package-lock.json in filtered source/build contexts.
- Very specific: line 83
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>.
≈ “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
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.rsdoes no IO, reads no clocks, takes(&PoolSnapshot, &SelectParams, now)and returns aDecision. All impure work (locks, CAS commit, timers) stays inscheduler/mod.rs. - State/runtime separation (herdr pattern):
PoolStatemutations are sync and IO-free behind a stdRwLock; never hold the lock across an.await. - No
unwrap()/expect()in production paths. Errors are typed (thiserror) and propagate;expectis 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-previewbrew formula → verify → hot-deploy + restart. - release (릴리즈 / "릴리즈해줘") — bump version → tag
v*→ CI stable release → refreshllmuxbrew 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 updatedocs/models.mdin 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.tomlversion, and the last version's tag already exists. Pick the next version with the user. - Preview publication includes the tap bump.
preview.ymldirectly 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.
runlaunches Claude Code;run --codexlaunches 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.jsonandpackage-lock.jsonin 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 andjust check-bridgein addition to the required Rust gate. See bridge contracts. - Local hot-deploy gotcha. The Cellar binary is read-only (
r-xr-xr-x), socpover it fails —rm -f "$(readlink -f /opt/homebrew/bin/llmux)"first, thencp,chmod 755, thenllmux restart. A laterbrew upgradeoverwrites 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 theSANITIZE_PATTERNS_SHAREDsecret, which 2lab-ai/soma-work holds with the same value;scripts/sanitize-scan.shis 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 configureduser.email(git's defaultuser@hostnameputs 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/usageendpoint returns percentages (0–100), not fractions — each evidence source has a fixed scale (seesrc/scheduler/usage.rs).
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.

