awesome-os-setup
AGENTS.md673 starsChanged 15 days agoMITView on GitHub
Canonical working rules for ALL AI agents in this repository (Claude Code, Hermes, Codex, ...). CLAUDE.md imports this file so all agents share the same rules and architecture guidance. - personal-os-setup: cross-platform Textual TUI app — OS/distro detection → package catalog → manager backends → system actions. Code in src/personal_os_setup/. - docs/: documentation hub published via properdocs/mkdocs. - src/awesome_os/ is dead — ignore it. - Package installs/upgrades/removals, chezmoi apply, shell changes, driver/VM/WSL setup, sudo steps: explicit, per-action user approval before…
- Reads credentials
- Installs packages
- 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 repository10 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- add-system-actionSkill
- chezmoi-scriptsSkill
- docs-siteSkill
- fork-and-customizeSkill
- repo-gotchasSkill
- run-testsSkill
- ship-featureSkill
- skill-layoutSkill
- vm-labSkill
The file
We split this AGENTS.md into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 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.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 43
Run make check before any PR.
- Distinctive: line 103
Corollaries: no third-party pack vendored as a copy.
- Very specific: line 172
Exceptions: always log (via the bound logger) then re-raise, unless inside a loop where one failure shouldn't abort the rest (see …
≈ “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
AGENTS.md
Canonical working rules for ALL AI agents in this repository (Claude Code, Hermes, Codex, ...). CLAUDE.md imports this file so all agents share the same rules and architecture guidance.
What this is
personal-os-setup: cross-platform Textual TUI app — OS/distro detection → package catalog → manager backends → system actions. Code insrc/personal_os_setup/.docs/: documentation hub published via properdocs/mkdocs.src/awesome_os/is dead — ignore it.
Safety: confirm before system-mutating actions (MANDATORY)
- Package installs/upgrades/removals,
chezmoi apply, shell changes, driver/VM/WSL setup,sudosteps: explicit, per-action user approval before running. A prior "yes" is not standing approval. - Destructive:
make vm-clean,make deploy-doc-gh(pushes gh-pages). Never bypass the TUI's confirm dialogs (SystemAction.confirm=False). - Git: NEVER run
git commitorgit pushwithout the user's explicit approval. Both are approved per action, every single time. A task description, a plan, "do the work", a previous approval, or an earlier push on the same branch is NOT permission. Ask, wait for the yes, then run exactly the action that was approved. The same applies to--force, PR creation/merge and release-branch actions. If an approval prompt times out, STOP — silence is not consent; say "prompt me again" is the user's call, not yours.
Config requests change the repo, never the machine (MANDATORY)
"Disable X in settings", "set Y in my config", "add this to my shell/editor" means edit the
Commands
| Command | Purpose |
make check | local gate: static/docs hooks, then test-all |
make test-local | safe unit + isolated skills suites; also the default pytest discovery |
make test-coverage | safe checks with separate Python coverage; no threshold |
make test-all | every self-contained suite: unit + skills, then the built-wheel install smoke |
make pre-commit | static/docs hooks incl. actionlint and zizmor; no dependency sync or hook installation |
make install-dev | full dev env and Git hooks (use this, not uv pip install -e .) |
make lint / make format | ruff directly |
make test-integration | CI only: Linux/macOS mutate packages; Windows is read-only |
Run make check before any PR. It establishes local validation; required CI additionally runs
self-contained checks and executed integration on Ubuntu/macOS/Windows. CachyOS integration is not
covered by hosted CI. make test-local alone omits artifact/runtime and strict documentation checks.
Full validation targets reject ARGS and PYTEST_ADDOPTS; use test-local ARGS="..." for filtered runs.
Conventions
- Branch: from
dev.feature/<name>/bugfix/<name>. - Commits: Conventional Commits, gitmoji optional.
feat→minor ·fix/perf→patch ·feat!/BREAKING CHANGE:→major · others→no release. Never bumppyproject.toml; never create tags — semantic-release does it. commitizen validates only atgit commit(commit-msg hook), not inmake pre-commit. - PRs: target
dev; promotedevtomainfor stable releases. Squash-merge, title must be conventional (= the release commit message). - Secrets: inline
# pragma: allowlist secret, never whole-file excludes. - Renovate: 7-day cooldown on dependency PRs;
uv.lockregenerated, not pinned. - Releases:
make release-statusreports branch, tree, origin sync, tag and GitHub release state without touching anything — run it first when a release refuses.make release-version/release-assets/release(scripts/release.sh) are what the main release workflow runs too. Guards:main/dev, clean tree, in sync with origin; CI binds to testedGITHUB_SHA, while local releases default toHEAD. The token isGH_TOKEN, else thegh auth loginsession, else a hidden prompt. Never run them, normake deploy-doc-gh, without per-action approval: they push, tag and publish. - Docs: developer pages live in
docs/developer/(numbered, one purpose line, short tables); update the page a change affects in the same change.
Index
| Topic | Where |
| Deep architecture (frontend, tasks, managers) | Architecture |
| Developer guide (setup, conventions, testing, release) | docs/developer/ |
| PR flow / ship process | .claude/skills/ship-feature |
| Documented-vs-reality drift | .claude/skills/repo-gotchas |
| Tests & coverage | .claude/skills/run-tests |
| Docs site gotchas | .claude/skills/docs-site |
| Repo skill layout / adding skills | .claude/skills/skill-layout |
| New TUI action / package-manager backend | .claude/skills/add-system-action |
| Chezmoi dotfiles source scripts | .claude/skills/chezmoi-scripts |
| VM test lab (CachyOS host) | .claude/skills/vm-lab |
| Forking this repo for your own setup | .claude/skills/fork-and-customize |
Skills & plugins — one rule: authored → the repo tree, third-party → npx
- Authored skills live in ONE tree, repo
dot_claude/skills/→~/.claude/skills(make skills-personal-repo-to-live). Codex gets per-skill links in~/.agents/skills;make skills-statusverifies them. Hermes reads~/.claude/skillstoo (skills.external_dirs), so nothing is duplicated into~/.hermes/skills— a name in both roots is unloadable (Ambiguous skill name … Refusing to guess);make skills-statusflags it. The saved set is listed inskills.keep; save a live skill into the repo withmake skills-personal-live-to-repo NAME=<name>. - Private content stays out: an
exposure: privateskill is live only (hermes curator pin) — this repo is PUBLIC. - Third-party, skills-only:
npx skills add <owner>/<repo> -s <skill> -a <agent> -g -y; npx keeps one canonical copy in~/.agents/skillsand symlinks it into~/.claude/skills(Linux/macOS only; Windows is not a target for third-party skills); the lock ($XDG_STATE_HOME/skills/.skill-lock.json, older CLIs~/.agents/.skill-lock.json) is copied into the repo (make skills-thirdparty-live-to-repo;make skills-thirdparty-repo-to-liveinstalls only what is missing or out of step,FORCE=1reinstalls everything). UseAGENT=codexfor Codex only. - Never vendored: agent-shipped (bundled / official optional) skills, plugin packs (that harness's
own channel, one install per harness), and the Claude account sync (
~/.claude/skills/synced/). Agent-created (Curator) skills are live only until triaged: promote, pin-private, or delete. - Corollaries: no third-party pack vendored as a copy; no upstream-shipped skill forked into the repo; no agent-created name left untriaged. One canal per pack per agent — never plugin and npx for the same agent (the model then sees one name twice).
- Transport for our own content is git +
makeonly — our skills never go through npx, a plugin, or a lock file; a tool that owns a directory must not own ours. - npx targeting — one name must be reachable by each agent exactly once.
-a claude-codealone already reaches Hermes (it reads~/.claude/skills), so never add-a hermes-agent: two roots Hermes reads →Ambiguous skill name … Refusing to guess.-a claude-code -a codexis safe (disjoint readers); never-a '*', which expands to that bad pair. Keep third-party names disjoint from shipped/deployed ones, and check before installing (the lock's twoNousResearch/hermes-agentnames are a documented exception — seeskill-deployment). - Three former entries are no longer in this repo:
skill-creatorwas vendored fromanthropics/skillsand is now served only by the Claude account sync — a second copy of that name collides with it and makes the name unloadable in Hermes.hermes-s6-container-supervisionwas a stale fork of the agent's official optional skill and is now installed from there instead (hermes skills repair-official <name> --restore --yes), not from this repo.nicegui-frontend-testingwas removed as unused. - Bundled (addon-shipped) skills are read-only: an edited copy is skipped by the sync forever;
put local additions in a skill we own instead and run
hermes skills reset <name>to unfreeze — see the shared skill-deployment skill.
Known drift (trust nothing blindly)
- actionlint and zizmor are active; pip-audit, bandit and markdown-link-check remain disabled in
.pre-commit-config.yaml make docker-prod/docker-devdon't exist- Docs said
_PRIMARY_MANAGERS_BY_DISTRO— the real constant is_UI_VISIBLE_MANAGERS_BY_DISTRO properdocs.ymlusesdocs_dir: .— new top-level dirs must join the exclude glob or they get crawled into the published site
Architecture
OS/distro detection → package catalog → UI
detect_os.py is the entry point for environment awareness:
detect_os()returns anOSInfo(family, distro, info)— family iswindows/darwin/linux/unknown; on Linux,distrocomes from/etc/os-releaseID(e.g.ubuntu,cachyos), and WSL is detected separately (_is_wsl(), checks/proc/sys/fs/binfmt_misc/WSLInteropor/proc/version).build_packages_for_os()loadssrc/personal_os_setup/config/packages.yaml(the single source of truth for installable packages, keyed by distro → manager → category → package list) and filters it to the current distro viaPackageCatalog.for_distro(), producing a flat list ofPackageRef(name, manager, category).
Package managers (tasks/managers/)
Each backend (apt, snap, brew/cask, winget, msstore, pacman/paru, webinstall) implements the PackageManager protocol in tasks/managers/base.py: is_installed, install, update, upgrade, cleanup. tasks/factory.py maps (distro, manager_name) → manager class in _PACKAGE_MANAGER_FACTORY_BY_DISTRO, and _UI_VISIBLE_MANAGERS_BY_DISTRO controls which managers are surfaced in the UI per distro (e.g. only apt shown for Ubuntu even though snap/webinstall also exist) to avoid duplicate buttons.
tasks/managers/_shared.py centralizes result-construction boilerplate reused across backends: command_details()/format_failed_command() (stdout/stderr → details text), sudo_required_task_result()/sudo_required_install_result(), missing_executable_task_result()/missing_executable_install_result(), and winget_path()/winget_list_shows_installed() (shared by the winget and msstore backends). Each manager still calls shutil.which(...)/sudo_non_interactive_ok() itself (not through _shared.py) so unit tests can keep patching those checks at the manager's own module path — _shared.py only builds the resulting TaskResult/InstallResult once the check has failed. Follow this pattern (local check, shared result-builder) when adding a new manager rather than re-deriving the boilerplate.
System actions (tasks/factory.py::get_system_action_sections)
This function is the other half of the factory: given (system, distro, info) it builds an ordered list of (section_name, [SystemAction]) used to render tabs/buttons in the TUI. It composes small per-domain builder functions (_package_manager_sections, _start_section, _dotfiles_section, _docker_section, _nvidia_section, _wsl_section, _advanced_wsl_section, _windows_utilities_section), each returning one Section (a (name, [SystemAction]) tuple) and independently unit-tested in tests/unit/test_factory.py. _start_section ("🚀 Start" tab) returns only the two doc-link actions — the onboarding walkthrough text itself is frontend-only markdown (app.py::_START_GUIDE_MARKDOWN), special-cased in compose() the same way the dotfiles tree is. Sections are assembled conditionally based on system/distro (e.g. zsh/chezmoi/docker sections only for linux+darwin, WSL sections only for windows, NVIDIA section for windows+linux). SystemAction supports plain actions (run), prompted actions that take free-text input (run_with_prompt + prompt_label/prompt_initial), destructive-action confirmation (confirm/confirm_message), and file backup before mutating config (backup_target). When adding a new system action, add it to (or add a new) per-domain builder function rather than wiring buttons directly in the frontend.
Task execution model
tasks/task.py defines the generic Task/TaskResult/run_tasks() primitives (idempotent check → run, catch-and-report exceptions as failed TaskResults) used by some system tasks; individual SystemAction.run callables in the factory return TaskResult directly and are invoked from the UI without going through run_tasks.
Frontend (frontend/)
Built on Textual (textual), not a web/GUI framework:
app.py(PersonalOsSetupApp) — the whole UI in oneAppsubclass, Textual-idiomatic (controller logic folds into the App rather than a separate controller class):compose()renders aTabbedContentwith a "📦 Packages" tab (SelectionList[PackageRef]+ install button +ProgressBar), one dynamically-generatedTabPaneper(section_name, [SystemAction])tuple fromget_system_action_sections(), and a "📋 Logs" tab (RichLog). A singleis_busy: reactive[bool]drives all busy-state UI (button disabling, the dockedLoadingIndicator, status label) through onewatch_is_busy()method — setself.is_busy = True/Falserather than updating widgets by hand. Background work (package installs, system actions) runs via@work(thread=True, exclusive=True)workers that call back into the UI thread withself.call_from_thread(...)— there's no manual job queue or poll timer; togglingis_busyfrom a worker thread must go throughself.call_from_thread(setattr, self, "is_busy", False)since reactive watchers touch widgets and must run on the app's own thread. Confirm/prompt gating (action.confirm,action.run_with_prompt) pushesdialogs.py's modal screens viaself.push_screen(..., callback). Job completion also callsself.notify(...)for a toast, in addition to the Logs tab.app.tcss— external Textual CSS (viaCSS_PATH), not an inlineCSSstring, so styling can be iterated on withtextual run --devlive-reload.dialogs.py—ConfirmScreen(Yes/No) andPromptScreen(label +Input+ OK/Cancel), bothModalScreensubclasses that dismiss with a typed result (bool/str | None) consumed by the pushing callback.main.py— thin entry point:sudo_preauth()thenPersonalOsSetupApp().run().
Frontend behavior is covered by tests/unit/frontend/test_app.py using Textual's headless App.run_test()/Pilot harness. When adding tests here, never click a button wired to a real package-manager/system action (e.g. real brew/apt/winget commands) — build a synthetic SystemAction with an in-memory run callable instead, the way the existing confirm-flow test does, so tests can't mutate the host system.
Settings/logging (settings.py)
ApplicationSettings (pydantic-settings) reads LOGGING_LEVEL from env/.env (default CRITICAL); logger is a loguru logger bound to name="personal-os-setup" with the default sink removed to avoid duplicate output — use this logger, not a fresh loguru instance, in new modules.
Code style
- Exceptions: always log (via the bound
logger) then re-raise, unless inside a loop where one failure shouldn't abort the rest (seerun_tasks). Preferif/else+ explicit raise over broad try/except when the failure condition is checkable upfront. - Docstrings: Google-convention docstrings are enforced by ruff (
Drules) except for the usual boilerplate exemptions (D100-D104,D107,D417); write them since they feedproperdocs/mkdocstrings generation.
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.

