gufo
AGENTS.md1.1k starsChanged 8 days agoMITView on GitHub
Production packages target Linux x86-64 AMD Strix Halo (gfx1151); Windows is a supported native build target for development. CMake owns compiler flags, dependencies and installation; Nix supplies the pinned toolchain. Linux source-build prerequisites are in README.md. Stage only task-owned paths before Nix builds; flakes include tracked files. Measure performance with result/bin/gufo or build/release/gufo. Preserve compiler/dependency versions when comparing results. Formatting and Python repository checks may run on the editing host; they do not need the remote GPU. Before committing C++…
Trending
More talk lately.about the whole repository
Who's talking about gufo-org/gufo
- @matheus23.com“Gufo is pretty impressive. Running Qwen 3.8 Flash Next on my strix halo machine locally is now feels …”Bluesky · Oct 1, 2026 · 5 likes
- ItzCrazyKns/Vane“Every request fails with 400 "unsupported keyword: $schema" against strict OpenAI-compatible backends”GitHub · Nov 6, 2026
- mecattaf/dotfiles“Load Gufo models through llama-swap and unload them when idle”GitHub · Nov 1, 2026
- neuhaus/gufo“perf(tp2): hand pending snapshot captures the MTP execution lock”GitHub · Oct 30, 2026
- LostVector/gufo“perf(cache): retain reused frontiers and active branch checkpoints”GitHub · Oct 30, 2026
The biggest 5 of 15 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 15
Talked about on GitHub and Bluesky (15 times).
On GitHub · 14
- Nov 6, 2026Every request fails with 400 "unsupported keyword: $schema" against strict OpenAI-compatible backends — ItzCrazyKns/Vane0 reactions
- Nov 1, 2026Load Gufo models through llama-swap and unload them when idle — mecattaf/dotfiles0 reactions
- Oct 30, 2026perf(tp2): hand pending snapshot captures the MTP execution lock — neuhaus/gufo0 reactions · 2 comments
- Oct 30, 2026perf(cache): retain reused frontiers and active branch checkpoints — LostVector/gufo0 reactions
- Oct 30, 2026perf(tp2): hand pending snapshot captures the MTP execution lock — LostVector/gufo0 reactions · 1 comment
9 more on GitHub
- Oct 29, 2026How does gufo get such high prefill on Strix Halo, and what can Maya take from it? — b-iurea/project-maya0 reactions · 1 comment
- Oct 27, 2026build: use ROCm 10.1 throughout Linux images — gufo-org/toolboxes0 reactions
- Oct 27, 2026ci: follow renamed Gufo Windows build workflow — gufo-org/toolboxes0 reactions
- Oct 27, 2026docs(bench): report Phoenix CUDA/NPU experiments — mikealanni/gufo0 reactions · 1 comment
- Oct 26, 2026Add Gufo LXC script — Heretek-AI/ProxmoxVE0 reactions · 4 comments
- Oct 25, 2026ci(release): attach Windows bundles to Gufo releases — gufo-org/toolboxes0 reactions
- Oct 22, 2026Podman container-proxy worker backend (retire llama-swap) — Syakyr/orchard0 reactions
- Oct 18, 2026Model IDs containing spaces are rejected — moooossee/moose0 reactions · 2 comments
- Oct 13, 2026update: gufo (gufo v0.20.0) — mecattaf/dotfiles0 reactions · 2 comments
On Bluesky · 1
- Oct 1, 2026Gufo is pretty impressive. Running Qwen 3.8 Flash Next on my strix halo machine locally is now feels entirely differently: llama.cpp: ~400… — @matheus23.com5 likes and reposts
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 repository3 other files it gives its agents.
- docs/AGENTS.mdAGENTS.md
- benchmark-modelSkill
- optimize-kernelSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
13 rules. About 0 are common, 7 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
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 43
Run the smallest check covering the change.
- Distinctive: line 70
Run once, investigate flags, then alternate main/PR only for affected histories.
- Very specific: line 85
Use tools/bench/build.sh for standalone HIP experiments, tools/bench/gfx1151_peak.hip for measured hardware ceilings, tools/prof/prof.py …
- Distinctive: line 93
Keep model code, tests, tools and numerical contracts with their model.
- Distinctive: line 94
Follow docs/AGENTS.md when writing or changing documentation.
- Distinctive: line 95
Use the shared Qwen control-token constants for framing.
- Very specific: line 98
Put Windows-specific code in src/core/platform/: one leaf per OS facility (files, pages, sockets), whose sources may branch on _WIN32 or …
- Distinctive: line 105
Use one canonical long option and backend name per behavior.
- Very specific: line 106
Use gh for GitHub operations after checking gh auth status.
- Distinctive: line 107
Follow Conventional Commits with a single-line message.
- Very specific: line 111
Prefer jj when available (jj version).
- Very specific: line 121
Run python3 tools/ci/check-extension-api.py --write after header/include changes.
- Distinctive: line 130
Follow the user's remote workflow and preserve unrelated work.
≈ “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
Platform and build
Production packages target Linux x86-64 AMD Strix Halo (gfx1151); Windows
is a supported native build target for development. CMake owns
compiler flags, dependencies and installation; Nix supplies the pinned toolchain.
Linux source-build prerequisites are in README.md.
nix build # development package, all discovered extensions
nix build .#release # shipped lock-mode package, no tests/tools
./result/bin/gufo diagnose
nix flake check # hosted CPU/repository checks
nix develop # GPU development and reference tools
# Same production build without Nix, with the documented dependencies installed
cmake --preset release # discovery build
# Add -DGUFO_EXTENSIONS_FROM_LOCK=ON for the shipped extension selection.
cmake --build --preset release --parallel 4Stage only task-owned paths before Nix builds; flakes include tracked files.
Measure performance with result/bin/gufo or build/release/gufo. Preserve
compiler/dependency versions when comparing results.
Focused tests
Formatting and Python repository checks may run on the editing host; they do not need the remote GPU. Before committing C++ changes, run the shared CI check:
nix shell --inputs-from . nixpkgs#clang-tools -c python3 tools/ci/check-format.py
# Add --fix to apply formatting, then rerun the check.Tests selected by nix flake check should stay fast and cache-friendly where
possible. Reuse expensive setup and compiler caches when valid, use the smallest
deterministic fixtures that preserve the assertions, and avoid redundant builds,
fixed sleeps and repeated whole-tree work. Measure added wall time; keep expensive
stress/model qualification explicitly selectable without weakening correctness.
Run the smallest check covering the change. gpu-test is RelWithDebInfo with
assertions enabled. Build only the affected target during iteration:
nix develop -c cmake --preset gpu-test
nix develop -c cmake --build --preset gpu-test --target <test-target>
nix develop -c ctest --preset gpu-full -R '^<test-name>$' --output-on-failureThe same CMake/CTest commands work outside Nix. cmake --build --preset pr
runs the focused contract subset after configuring cpu-test; nix flake check
runs the canonical CPU/repository gate. Full CPU checks,
sanitisers, GPU/operator/model checks and H3 quality tools remain available
locally; see docs/internal/testing.md. Do not run full model sweeps,
video generation or duplicate suites for routine edits. A missing-model skip
is not a quality pass. Broaden checks when shared behavior changes or failures
expose risk.
Text API functional/regression tests live in tests/functional/.
Select suites explicitly. Model-specific changes need the affected model/modes;
use all four profiles only for shared behavior changes. Run correctness on the
candidate; use main for matched affected timing controls and suspected regressions,
not a duplicate full correctness run. Reuse baseline evidence only when revision,
toolchain, harness, model, settings and cache history match. Include long-context
and cache for continuation changes; verify loaded mode and actual drafts.
Correctness and expected prefill/cache work are strict; timings are
mandatory per request/phase at 5% and 10 ms, never averaged across requests.
Run once, investigate flags, then alternate main/PR only for affected histories;
use unchanged-main controls when needed and retain every result. Fix confirmed
regressions before publishing. Noisy evidence stays visibly inconclusive and
unqualified; do not widen margins or stop at reporting failures. Devlab keeps
inconclusive timing advisory on both ordinary and release PRs. Use the code
diff to select affected metrics; unrelated timing variance does not justify
another full matrix.
For reported coding-agent loops, also replay the affected workflow with
tests/functional/pi_agent.py; retain its sessions and inspect actual tool results.
Retain numerical quality tests and the standard speed benchmark. Keep these
tests in tests/functional/, outside hosted model CI; avoid full sweeps.
Profiling and kernels
Apply .agents/skills/optimize-kernel/SKILL.md.
Use tools/bench/build.sh for standalone HIP experiments,
tools/bench/gfx1151_peak.hip for measured hardware ceilings,
tools/prof/prof.py for pipeline/wall-time profiles, and
tools/prof/isa_mix.py for instruction analysis. Production paths must retain
quality; successful optimizations become the default, without extra switches.
Development
- Keep model code, tests, tools and numerical contracts with their model.
- Follow docs/AGENTS.md when writing or changing documentation.
- Use the shared Qwen control-token constants for framing; see src/families/qwen/AGENTS.md. Inspect their definitions when reviewing or changing behavior, and keep reference fixtures independent.
- Put Windows-specific code in
src/core/platform/: one leaf per OS facility (files, pages, sockets), whose sources may branch on_WIN32or split into<leaf>_posix.cpp/<leaf>_windows.cppselected in CMake. Outside it and vendored code, call the leaf, with nowindows.hor_WIN32/_MSC_VERchecks. POSIX code moves into a leaf, verbatim, once it gains a Windows counterpart. Never emulate POSIX with macros or copy a file per OS; when the logic itself differs, add<file>_windows.cppbeside it. - Use one canonical long option and backend name per behavior; avoid aliases.
- Use
ghfor GitHub operations after checkinggh auth status. - Follow Conventional Commits with a single-line message. Title pull requests
according to the release policy; squash merging retains
that title on
main. Mark breaking changes with!in the title, and leave version and changelog updates to the release workflow. - Prefer
jjwhen available (jj version); otherwise use Git. - The source extension API is versioned independently from Gufo. Public headers
under
include/gufo/ext/, their transitiveSURFACEclosure (including forwarded core/cache headers), the metadata schema and public CMake contracts require anext-apiPR label and one new, uniquely named Markdown record underinclude/gufo/ext/changes/<major>.<minor>/when declarations/contracts change. Records are permanent and immutable. CMake derives the API revision from the active series ininclude/gufo/ext/api-series.jsonplus its revision-record count. Thebaseline.mdrecord documents the initial contracts without advancing it. Do not manually bump versions for additive changes. Runpython3 tools/ci/check-extension-api.py --writeafter header/include changes; the PR diff gate also checks forwarded declarations. Before 1.0, a minor bump may break extensions; revision bumps are additive. Fix in-tree users together. The guarantee is source compatibility after rebuilding, never binary ABI. Breaking changes explicitly advance the compatibility series in api-series.json and add a record in the new series, retaining all historical records. Extension API and the future experimental flakeextensionsargument are excluded from Gufo's release compatibility surface; CLI/HTTP/public existing flake breaks still require!. See the release policy. - Follow the user's remote workflow and preserve unrelated work.
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.

