Merged
Conversation
Overhaul for the public launch. Three new/rewritten files at the root
cover the three ways a contributor (human or AI) might arrive at this
repo:
1. llms.txt (new) — llmstxt.org-style discovery file. Written for AI
agents that land here for the first time. Start-to-finish install
sequence (prerequisites → npm install → build:all → install-link →
verify), a first-use pattern, where to go for deeper context, and
explicit "things not to do" (no smoke runs without asking, no tags
without permission, etc.). An agent that reads this end-to-end can
install ghax and start driving a browser without any other context.
2. AGENTS.md (new) — generic agent memory file. What Codex, Cursor,
Aider, Continue, and Windsurf read when working inside the repo.
Covers hard invariants (CLI-is-Rust / daemon-is-Node separation,
single-daemon-per-state-file, ref lifetime, daemon restart rule),
build commands, full project layout, how to add a new verb, code
style, voice guidelines, and the confusion protocol. CLAUDE.md is
now a thin extension pointing at this file so we aren't
maintaining two parallel memory files.
3. README.md (rewrite) — public-facing. Leads with the live demo, a
"why this exists" paragraph, and a prominent "Install with an AI
agent" section with a single-paste prompt:
> Clone https://github.com/kepptic/ghax and follow the install
> steps in its llms.txt file. Verify with `ghax --version` and
> report success.
Profile modes rendered as a table (real / dedicated / scratch).
Command-reference section explicitly states there are no man
pages — `ghax --help` is authoritative — and documents exit
codes. AI agents section covers Claude Code skills (three install
paths + verify), Codex/Cursor/Aider/Continue/Windsurf (AGENTS.md
convention with a drop-in snippet for adding ghax to another
project), raw-shell harnesses, and multi-agent isolation.
CLAUDE.md and CONTRIBUTING.md get one-paragraph updates pointing at
the two new files. Everything else (SECURITY.md, CODE_OF_CONDUCT.md,
CHANGELOG.md, LICENSE, ARCHITECTURE.md) is already in good shape and
untouched.
kepptic
added a commit
that referenced
this pull request
Apr 24, 2026
docs: llms.txt + AGENTS.md + modern README
kepptic
added a commit
that referenced
this pull request
Apr 24, 2026
docs: llms.txt + AGENTS.md + modern README
kepptic
added a commit
that referenced
this pull request
Apr 24, 2026
docs: llms.txt + AGENTS.md + modern README
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.
Public-launch doc overhaul. Adds
llms.txt(AI-agent discovery + install-from-clone guide per llmstxt.org) andAGENTS.md(generic agent memory: invariants, build, project layout, how to add a verb). Rewrites README with a prominent "Install with an AI agent" paste-this prompt, profile-modes table, and explicitghax --helpas the authoritative command reference. CLAUDE.md and CONTRIBUTING.md get one-paragraph pointers to the new files.