With the docs team, there’s a lot we can explore and I trust them to also work towards the best solution here together with the community.
@hsjobeki maybe we do a small round table discussion at NixCon in general?
7 Likes
@7c6f434c Can you expand on this? This seems to touch upon the goals I have.
I do not know which of the public and semi-public announcements will go to a useful state. I hope that out of a few government setup bids with use of Nix at least one will go to enough deployment, for example.
1 Like
I’d love to have that discussion.
1 Like
I skimmed through this thread hoping to understand what the original/core intention is beyond the vague urge to do something because of “the LLM trend”. But I am not sure whether this has been addressed so far. At least for me it only surfaced here and there and fundamentally the what and why is missing for me, still.
For example, if something is missing documentation: This has nothing to do with LLMs. Maybe it is good to “just” document it.
or
Something is not very easy to do or hard to understand: Maybe it should be made easier instead of obfuscated by abstracting it away into a SKILL.
This is not me saying I do not see value in having a hypothetical SKILL.md for e.g., “desktop machine administration via nixos-rebuild”.
But maybe I am just not getting the intent/idea.
18 Likes
Thought I’d throw my hat in the ring here. I just switched from Omarchy to Nix.
I spent a few weeks going through the official docs and guides. Those helped me get my primary packages migrated to home-manager and a configuration.nix file on my Omarchy install. They helped me get a VM set up where I could practice the installation of my configurations on top of a fresh NixOS install.
But at various points I fell into gaps where either there was something that I was trying to do that the guides, or any other documentation I found didn’t address, or the ones I did find were older and were incompatible with the approach I had taken.
Using LLMs to fill those gaps got me to a working system that I am very happy with. I am certain that as I go through and review the code, some of it will be over-complicated and cringe-worthy–and moreso, the more I learn. But I’m here and enthusiastic. Chatting with some of my Discord colleagues from the Omarchy channel, there is a curiosity with Nix, but many who have tried found parts of it crushingly hard, and many who haven’t are afraid of it.
In addition to just getting unblocked, I found LLMs to be very useful for configuring the window manager and desktop shell. There is a very compelling workflow there that is just starting to be explored in spaces like the Omarchy community and elsewhere. It is ironically far easier to do this with Linux than in Windows, where Microsoft has spent millions of dollars investing in using LLMs to make the most minor of configuration changes.
I was also able to do most of the work from a locally hosted Qwen3.5-DeepSeek4 distillation that could fit on the VRAM of my old pandemic era AMD GPU, so while there were some original harms that went into creating these models, a small, well tuned open-source/weight model can be deployed for most of these tasks without needing to put a data center in someone’s backyard.
There were a few times where I had to switch to a hosted version of qwen3.6-plus to get the answer I needed, but only a few.
All of that is to say, I think the docs and guides are great! That said, as a veteran to Linux but a newbie to Nix, there are lots of little architectural decisions and patterns for which I saw very little written about it, or was written for pre-flake versions of Nix. Or where there were plenty of guides, but I just had to wade through a slog of errors to get the shape right.
Some of the challenges I ran into were:
- how to organize flakes that contained private but not sensitive details that should live in a private repo, but still be consumable from my primary flake which lives in a public repo
- Creating overlays and derivations for packages that needed patches, minor adjustments, or specific versions that were not yet available in nix-pkgs
- Navigating the various approaches for getting my 15yo Brother printer and scanner working
- Understanding why and when to (not) use home-manager vs configuration.nix
- How to break pieces of a larger, existing config out into their own flakes from an existing config
- Understanding when to have Nix manage a configuration in its read-only store vs placing a file from the repo and setting up symlinks (allowing me to do live updates to my desktop config)
- Getting display rotation and lid open/close events from my laptop wired up as Nix-owned systemd services
…And a bunch more.
I found skills like context7 which allows your agent harness to pull from documentation sites to be invaluable.
One of the most impressive things about Omarchy is that you can quickly get up and running with a TUI-driven development system. I just quickly found that while I liked many of the ideas of that system, I disagreed with most of its design and software decisions (particularly the introduction of DHH-backed software pre-installed as bloatware, and Hyprland doesn’t have layouts which work well with some of my use-cases like using DAWs for recording music).
In my short time using the new Nix system, and with the help of all LLM, I was able to get my own Omarchy like install very quickly, but more over, I now have several flakes that I could hand to someone with a 2-in-1 laptop and reasonably expect them to get up and running on their first config switch. I have navigated these configs with various versions of Ubuntu, and it was always painful until they were properly baked in to the distro release. Using the LLM, I was able to get these configs in place effortlessly.
Using Mango and Noctalia got me to a system that is more flexible while still allowing me to leverage TUIs, keyboard driven navigation, and so on.
Looking at projects like [Nixbook](nixbookos.org), there’s a lot of room to make well thought through systems with Nix for non-technical people. LLMs on top of those baseline systems give them a path to get their configuration (particularly at the window management and desktop shell layer) further without having to be deeply knowledgeable about Linux systems.
Happy to provide further details about obstacles I ran into and approaches I took which might be helpful.
4 Likes
Knowledge is freely (0 currency, contractually unbound, anonymously, etc.) available; the LLMs with the greatest chance of being effective are not. Users do not benefit from the obfuscation of knowledge that shoving LLMs into the OS would entail. NixOS users don’t deserve a walled garden.
All of this is available on this very forum you’re commenting on. If you don’t understand, you can just ask.
10 Likes
I hear what you are saying, but I don’t agree that there is a walled garden created by using an LLM. And saying that the path is not well paved for all users is not the same as saying it can never be so. I’m only trying to point out opportunities.
The biggest challenge I had was that there was too much information out there, and it was hard to get a cohesive, definitive path forward. Each path required a lot of roomba-ing against different walls as I tried to understand how the pieces fit together.
I did do a lot of reading in this forum, but trawling through forum posts isn’t always a great medium for learning, or learning what is best for my situation. It is also very time consuming, and communicating goals in long asynchronous threads is not always helpful when you are just trying to get things to work. The hardest part about learning new things is knowing what questions to ask, or understanding what a full implementation should look like.
I’m a big fan of the adage of “first get it working, then get it working well, then get it working fast”. Sometimes taking shortcuts to that first step makes more room for nailing the latter two, even if there’s some technical debt to clean up. It’s the very nature of prototyping.
In my experience, an LLM made those pathways much easier to navigate. Now I have something that works, and that I can work backwards from. I can study each flake pattern, derivation, overlay, and goal and interrogate them, go back to the docs to learn the particulars, and then create new guides and articles, or contribute back to the existing guides with the benefit of having walked a path without getting frustrated and giving up.
That doesn’t absolve LLMs of all their problems, but I’m just trying to call out that there are beneficial paths, and as the original poster pointed out, people are going down these paths without anyone’s permission, and not all of the outcomes are inherently bad.
Said differently, not all the new ways are great, that doesn’t mean all the previously existing ways offer all the best answers to all situations.
These are just tools.
3 Likes
Nix is hard because of the scope of its undertaking, which is effectively to force an uncooperative world of software to see the world its own way.
And as long as that is true, and nix itself can’t deliver relevant help on demand as a user is trying to solve their problem, no quantity of documentation will help. The documentation we already have in my opinion is really good! Almost anything you want to know how to do is in it. People don’t read it, they just complain about its fictional non-existence instead. Getting started with nix is a fractal of exploration unless you already have a good grasp of the fundamentals of how linux fits together and how your programs source their configuration, potentially how compilers work and how they source their configuration, how your desktop works and how it sources its configuration. And all of this before grappling with nix’s own tower of abstractions. You’ve got to be in it for the long haul if you don’t want to be frustrated.
Personally I think until there is a step change in the quality of deterministic machine-readable feedback from our tools we are doomed to hear an endless repeat of the same discussions which all seem to dance around the fact that at the bottom of it an un-typed lambda calculus a-like, with every major feature depending on late-binding though stacking lazily-evaluated fix-points, which ultimately feed the moral equivalent of a giant script capable of rebuilding the entire fs outside of the store is not friendly. Documentation can’t fix that.
Arguably LLMs are scaling to what the community can’t do, which is provide timely (and by timely I mean being on-call for help requests), specific, and tailored help to people wanting to learn about nix. Fortunately, they need no particular help in this regard, and if you have an mcp feeding legit options, they can get to a solution pretty fast, so expending any effort there (i.e. agent specific docs) seems to me to be a total waste of the sparse resources we have.
9 Likes
The documentation we already have in my opinion is really good! Almost anything you want to know how to do is in it.
Totally agree. I did read through a lot of the docs and guides, but as someone who is a project-based learner, there’s only so much I can read before I have to operationalize those learnings. And there will never be documentation for my exact setup until I create it.
But my config repo is now a new learning path made just for me. I can now review everything in there and comb the docs, guides, and forum posts to absorb the finer details, so I can make more informed decisions around where to go from here.
Most folks don’t need that though. Getting back to the Nixbook project, it–imo–is everything that is good about the Omarchy project without any of the baggage. Different audience, and different goals, but it takes all the things that 90% of folks will never want or need to touch, and it uses Nix’s strengths to make those bits resilient and invisible to the user. Folks can go deeper if they want, but if you just want a Chromebook experience on old hardware, it’s a problem that is solved.
I can see a possible (maybe not everyone’s ideal, but possible and powerful) future where there are lots of Nix-based micro-distros with different baselines all set up, and users just interact with a small, well tuned, on-device LLM (I.e. it can run on most mid-tier laptops with no discrete GPU) that helps non-technical users set up a repo for their custom configurations and overrides and field their desired adjustments.
I’ve been supporting my parents on Ubuntu for almost 20 years. They like it more than Windows, and once they were set up, they didn’t need a ton of help outside of a few odd-corner situations. I would never ask or expect my parents to set up a NixOS install, but I can totally see myself setting one up for them that I would then support and maintain.
3 Likes
I logged in for the first time in a while to respond to this. There’s quite a few personal opinions presented as fact here.
lms.txt will be the hear and soul of Nixos documentation in the near future.
citation needed.
The Nix community should embrace and guide the usage of Ai in nixos.
why?
Times have changed, user base is changing, if Nixos is to survive we need to change as well.
This is a beautiful example of three logical fallacies in one sentence. Bravo. Appeal to Novelty, Slippery Slope, and Appeal to Fear.
The solutions is not gate keeping, and using politics for every conflict and everything we do not agree with.
Why is preferring human-written documentation for human gatekeeping or politics? I disagree that we need agent docs at all in NixOS. I don’t think that’s a political statement.
It seems like you’ve found some gaps in the NixOS documentation and found some pain points that new users will experience. Why not help with documentation rather than force your AI docs on other users?
I’m personally not a fan of AI or the companies behind them, but why does every enthusiast immediately cry “no politics” when someone isn’t a fan here? I’m against the idea of renting reasoning and critical thinking skills from feudal overlords and I don’t like how they’re disrupting communities by forcing large data centers on them. I’m sorry if this reality makes you uncomfortable but it’s not something you can just ignore.
Lastly, DHH is an awful human being. His vibe coded “distro” isn’t something to aspire to. See: As I remember London
20 Likes
This is a long thread, so I’m sorry if this has been discussed and I missed it, but what does this mean? What does it look like in implementation? I don’t ask this in argumentative way, but as I understand it, these machines are very good at reading text (iirc “reading” lots of text is how they were created in the first place). If this is so, doesn’t making human-oriented documentation better also make it better for agents?
5 Likes
No, that’s not what “documentation” is. What you’re talking about is an “ANN Index”, and it’s probably good to have that too. Somewhere. Did you start building one?
As far as priorities go, though, I still find the “documentation” a more urgent matter than “agent support”
5 Likes
The problem with your reasoning is that your original suggestion was to create documentation primarily tailored to LLMs and second to humans.
Getting anything merged into a community repo does take work by both the contributor opening the pr and by the rest of the community in the form of review. Because of this, your suggestion to “just add AI docs” to nix repos is not just an opinion, you are pressuring someone to work on your suggestion by using disingenuous tactics such as FOMO (fear of missing out) in your very first post of this thread.
These very tactics are a core part of the marketing campaigns of various LLM companies, which is the reason people feel offended and respond in kind.
As for shutting down discussion. From what I can see the discussion so far was:
- You suggesting LLM-first documentation, assisted by LLMs themselves
- Mihaimaruseac (and most everyone else) dismissed the idea to focus on LLM documentation over documentation for humans on the basis that LLMs can read the latter just fine. Something that got backed up by several people using LLMs.
- Tomberek suggested an external repo to quantify whether documentation for LLMs have additional advantages
- Your argument of starting somewhere and that one doesn’t exclude the other
- ElvishJerricco pointing out the law of scarcity, any one action has to be done in favor of another
- theutz pointing out that documentation burn-out exists and that LLMs are in general not good at writing good docs
So unless you can prove that more LLM tailored documentation results in sufficiently higher quality agents I don’t see anything left to discuss. This starts by having people test your external repo as an input for their agents.
23 Likes
The beginnings of this was done by the Nixpkgs Core Team that it yielded improvements over the status quo; even for a tiny change to just point the agents at the existing policy.
In the spirit of @uninsane’s suggestion for a reproducer and our suggested principle of only adding what’s empirically necessary over our existing documentation, I took the liberty to do a before‐and‐after comparison, using Claude Code 2.1.187 with Claude Opus 4.8 and the prompt “Please move the
gnugreppackage topkgs/by-nameand open a pull request.”, one time without aCLAUDE.mdand two times with it. (Note that I sandboxed it to be unable to read the GitHub CLI’s token, and do not use a token with write access for that anyway, so there was no chance of a PR being opened, and it is possible that the sandbox denials caused different results than I would have seen without them.)…
That seems like an improvement on the status quo, where you can clone Nixpkgs and get an automated PR sent off without ever becoming aware that we even have a policy. It was still not optimal (e.g. I would prefer to see our entire PR checklist mentioned), but I didn’t see any counterproductive increase in fully‐automated behaviour; it was much more obvious that human review and oversight is required in both cases than without our suggested wording, and the essential requirements of the policy went from never coming up to being foregrounded.
3 Likes
Let’s not do this again…
10 Likes
The comment you linked said pretty much the opposite of what you’re saying though?
First off, the Nixpkgs core team agree that we shouldn’t silo generally‐useful documentation off solely for LLM consumption, per #536668 (comment). If we have discoverability issues with our contributor documentation, or we’re missing a valuable summary of the most important requirements, those are likely to be things that human readers would benefit from too.
Therefore, if an
AGENTS.mdexists, it should primarily be an entry point that refers to our existing documentation. Any additions beyond that should either be things that are only relevant to coding agents, or things that we can empirically observe are sufficient for human readers but fail to elicit the desired behaviour from coding agents and that are sufficiently important to warrant reiterating.
The point was that any documentation that’s useful to humans should exist in human-targeted documentation, not in LLM-targeted documentation. I feel like the statement was extremely explicit about that? That’s why the experiment you quoted specifically only directed the LLM with a pointer to the human-targeted documentation. They said that the only documentation that should be LLM-targeted is stuff that is “only relevant to coding agents”, i.e. only things that are literally completely irrelevant to humans. I really don’t think this supports your point at all. If anything, the experiment supports that human-targeted documentation is the right call because it does help agents.
15 Likes
The way people have set up their LLMs has drastically changed in the last two years and I am not certain those ways are stable yet or will be stable in the foreseeable future. This possible creates a lot of churn, whenever someone drives by with their 100x something improving skill.
More importantly however the way people use them is also different. A lot of people have their own workflow with them, not unlike people using different editors. As an example I refuse to use any LLM not hosted on my own machine.
Due to me not having build a data center in my back yard, I am constrained with what I can put in the limited context window. I don’t want to fill it with information about how to open a pull request, something I don’t want my agent doing anyway.
For these reason I think we should treat LLM specific documentation like we treat envrc[1] and leave it up to the user to add those things. A quick search with your favorite search engine already pulls up lots of options for those.
There also is the same fear as in that pr, that someone injects malicious instructions into the LLM documentation. ↩︎
8 Likes