Add llm.txt: a setup runbook an agent can execute - #5
Merged
Conversation
Someone asking an agent to "set this up for me" gets a README written for a human reading top to bottom — prose, alternatives, rationale — and the agent has to reconstruct an ordered procedure out of it. This is that procedure, written to be executed rather than read. The parts a README does not carry, and an agent needs: A VERIFY after every step. The characteristic failure here is silence — a key that was never bound, a hooks block pointing at a moved binary, a status segment whose #() cannot resolve the command. All of them look exactly like "no agents are running", so each step has a command that distinguishes the two, including a headless capture that proves the picker draws without asking the user to press anything. ASK points, marked as such. Which key, whether they want the agent half at all, and — because this one took several rounds to get right — whether their status-right is hand-composed before appending to it. Also whether they have a Nerd Font, which cannot be detected and which decides between a status bar and two boxes of tofu. Conflict checks that have actually caught something. `show-hooks -g | grep set-tab-title` finds the case where @kaku-tab-titles would fight the user's own hooks; it fires on this very machine. Sourcing twice must leave one copy of the status segment. Every check in that section is a real failure, not a hypothetical. And the two silent status-bar traps: -agF expands the format at load and freezes the count forever, and #() runs with the PATH the tmux *server* inherited, which under launchd or systemd has neither /usr/local/bin nor ~/go/bin. Closing sections tell the agent to report what it changed and where the backups are, and map symptom to cause, so the person is not left with an edited config and no idea what moved. Every command in it was run against a live tmux server before it was written down. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Someone asking an agent to "set this up for me" gets a README written for a
human reading top to bottom, and the agent has to reconstruct an ordered
procedure out of it.
llm.txtis that procedure, written to be executed.What it carries that the README does not:
A VERIFY after every step. The characteristic failure mode here is silence —
a key that was never bound, a hooks block pointing at a moved binary, a
#()the tmux server cannot resolve. All of them look exactly like "no agents are
running". Each step gets a command that tells the two apart, including a
headless capture that proves the picker draws without asking the user to press
anything.
ASK points, marked as such. Which key; whether they want the agent half at
all; whether their
status-rightis hand-composed before appending to it; andwhether they have a Nerd Font, which cannot be detected and decides between a
working status bar and two boxes of tofu.
Conflict checks that have caught something real.
show-hooks -g | grep set-tab-titlefinds the case where@kaku-tab-titleswould fight the user's ownhooks — it fires on the machine this was written on. Sourcing the config twice
must leave exactly one copy of the status segment.
The two silent status-bar traps —
-agFfreezes the count at load time, and#()runs with the PATH the tmux server inherited, which under launchd orsystemd has neither
/usr/local/binnor~/go/bin.It closes by telling the agent to report what it changed and where the backups
are, plus a symptom-to-cause table, so the person is not left with an edited
config and no idea what moved.
Every command in it was run against a live tmux server before being written
down. Docs only — no code changes.
🤖 Generated with Claude Code