Lilo
AGENTS.md58 starsChanged 10 days agoMITView on GitHub
Rules for coding agents (and humans) working in Lilo. Bias toward small, KISS changes - ROADMAP.md lists the non-goals.
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 33,315 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 repository6 other files it gives its agents.
- docs-site/AGENTS.mdAGENTS.md
- site/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- docs-site/CLAUDE.mdCLAUDE.md
- site/CLAUDE.mdCLAUDE.md
- changelog-draftSkill
The file
We split this AGENTS.md into the rules it gives an agent
5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
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 11
After adding or renaming a Swift file, run make project-sync and commit the regenerated Lilo.xcodeproj - xcodebuild and CI fail until it is …
- Distinctive: line 20
Efficiency first: Do the least work possible: no polling, no redundant renders or recomputation, no resending unchanged data, nothing at …
- Distinctive: line 21
Comments: only for what the code cannot say: a constraint, a non-obvious why, a deliberate oddity.
- Very specific: line 23
Commits: follow Conventional Commits (fix(sidebar): ...), one logical change each.
- Distinctive: line 30
Extension Gap APIs: - add one only when WebKit lacks the Chrome API *and* a real extension flow needs it.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 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
Rules for coding agents (and humans) working in Lilo. Bias toward small, KISS changes - ROADMAP.md lists the non-goals.
Build & verify
- The Makefile is the only command surface. Don't invent build steps;
make helplists everything. make validateis the gate - UI lint/tests, the extension bridge build and tests, SwiftLint, the Xcode build, Swift tests, commit hook and perf summary tests, website and documentation site checks and tests, and the release-note and version checks (release-status). Run it before claiming a change outsidelilo-ui/works. It should stay around 30 s warm: write tests that keep it there (CONTRIBUTING.md). (CI additionally runsmake e2eandmake swift-test-slow, checks thatLilo.xcodeprojand the generated extension bridge bundles are in sync, and builds Release.)- Scope the checks to what changed. A change confined to
lilo-ui/(Svelte, TS, CSS, locales) needs onlymake ui-lint ui-test, and one confined todocs-site/onlymake docs-check docs-test; keepmake validatefor changes that touch Swift, the bridge or the build. A change to a file the docs site's reference generator reads (the watch paths in docs-site/README.md, such as the shortcuts, the settings model, the agent tools, the catalogs andCOMPATIBILITY.md) also needsmake docs-check. swift build/swift testare fine for fast local checks oncemake vt-buildandmake ui-buildhave producedVendor/and the generated sources;xcodebuild(viamake) is the official path. Run directly, it takes-derivedDataPath .derived.noindex/xcodeasmakedoes, so a worktree's build goes with the worktree.- After adding or renaming a Swift file, run
make project-syncand commit the regeneratedLilo.xcodeproj-xcodebuildand CI fail until it is synced.
House style
- KISS. Minimum code that solves the problem. No speculative abstraction, no single-use protocols, no config knobs with one caller. If it could be half the size, rewrite it.
- Generic, never per site. Fix a site's problem with the web platform or a mechanism every site gets: no hostname check, no reliance on a site's markup, class names or internals, no user agent for one site. Such a quirk breaks silently on the site's next deploy and helps no other site. The existing Meet modules are no precedent. When no generic fix exists, say so and document the limit in COMPATIBILITY.md.
- Surgical diffs. Touch only what the task needs and match the surrounding style. Don't refactor code that isn't part of the task.
- Placement. A new file goes where the placement rule says; tests mirror source paths.
- Design bar: Apple and Arc. Every screen and interaction must feel like a first-party macOS app with Arc's polish: native conventions (HIG spacing, SF Symbols, system fonts, standard shortcuts and menus), calm motion that respects Reduce motion, no layout jumps, nothing clipped or misaligned, AA contrast, every control reachable by keyboard. If it would look out of place in an Apple app, it is not done. docs/DESIGN.md holds the consistency rules every screen follows.
- Efficiency first. Do the least work possible: no polling, no redundant renders or recomputation, no resending unchanged data, nothing at idle. A feature that costs CPU, memory or battery when unused is a bug.
- Comments only for what the code cannot say: a constraint, a non-obvious why, a deliberate oddity. Never restate the next line or record history. Code, comments and commit messages are in English; user-facing copy is translated.
- No real user data in tests, fixtures, docs, commits or release notes: a URL, page title, folder name or account seen while debugging is replaced by a made-up equivalent (
example.comhosts, generic names) that reproduces the same case. - Commits follow Conventional Commits (
fix(sidebar): ...), one logical change each. - The WebKit fork is optional. Lilo is built for the WebKit that ships with macOS, and every feature works on it alone: the fork only brings engine bug and performance fixes early, and runs only while it holds every security fix of the installed macOS. Never build on an API or behavior only the fork has. See docs/WEBKIT_FORK.md.
- One web engine (WebKit), direct dependencies only. Terminal tabs use libghostty-vt from a pinned Ghostty commit:
make vt-builddownloads it prebuilt and checksum-pinned,make vt-build-sourcecompiles it with Zig.
Gotchas
- Localization - user-facing strings live in
lilo-ui/src/lib/i18n/locales/*.json; add every key to all catalogs (themake ui-testparity check fails otherwise). Native AppKit strings use.localizedunder thenativenamespace. See docs/I18N.md. - Extension Gap APIs - add one only when WebKit lacks the Chrome API and a real extension flow needs it. A Swift handler must be paired with JS augmentation, and COMPATIBILITY.md must be updated: it describes only what still differs from Chrome. See CONTRIBUTING.md.
- Page-world APIs - anything a web page can see goes through
PageWorld(handlers in its bridge world, modules patching WebKit's prototypes): a global, a page-world handler or a function printing its source flags Lilo as a bot.PageWorldTestsfails on any such trace. See docs/ARCHITECTURE.md. - Private WebKit API - guard every private selector with
responds(to:)and degrade gracefully when it is missing; register new private delegate hooks inPrivateDelegateSelectorTests. See docs/ARCHITECTURE.md. - Release notes - a change people using Lilo will notice gets a note from
make change, committed with the code under.changes/unreleased/; without a prompt, run the Makefile's$(CHANGIE)asnew --interactive=false -k <Kind> -b <text>. Never editCHANGELOG.md:make release-versiongenerates it from the notes. A release's website story and What's New highlights come from thechangelog-draftskill, run locally and reviewed like code; they never hold a release back. See docs/RELEASING.md. - CSS
:has()is fine, but not always the best tool: a broad one makes WebKit recheck its whole container on each change inside. When Svelte state already knows the condition, a class is simpler and cheaper. - Generated files - every
*.gen.*file, theChrome*.jsbundles andChromeAPIGapModules.jsoninLilo/Extensions/,Lilo/Extensions/public-suffix-list.dat, plus the git-ignoredLilo/Generated/NativeStrings.swift,Lilo/Generated/ChromeUIAssets.swiftand the documentation site's reference partials (docs-site/content/reference/_generated/, and its French shortcut and settings tables) are build outputs - never hand-edit them. Regenerate them withmake ext-bridge-build(extension bundles),make bridge-gen(*.gen.swift,tabProtocol.gen.ts),make ui-build(NativeStrings.swift,ChromeUIAssets.swift),make emoji-data(emojiData*.gen.ts),make public-suffix-list(public-suffix-list.dat,topLevelDomains.gen.ts),make chrome-surface(chrome-constants.gen.ts) ormake docs-build(the documentation site's partials).
For website changes, read site/AGENTS.md for Astro-specific rules; for the documentation site at docs.getlilo.app, docs-site/AGENTS.md.
Architecture deep-dive: docs/ARCHITECTURE.md. Setup, tests and the pull request flow: CONTRIBUTING.md.
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.

