2026-10-17 12:08:30 -05:00
|
|
|
---
|
|
|
|
|
title: "Project context"
|
2026-10-20 13:51:34 -05:00
|
|
|
summary: "Give the agent your project's conventions in AGENTS.md, and how luxe finds the project."
|
2026-10-17 12:08:30 -05:00
|
|
|
order: 3
|
|
|
|
|
group: "Customize"
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## AGENTS.md
|
|
|
|
|
|
|
|
|
|
Put your project's conventions in an `AGENTS.md` at its root, and the agent reads it at the start of
|
|
|
|
|
every session. In a project folder a `CLAUDE.md` works too; when both exist, `AGENTS.md` is used.
|
|
|
|
|
The global files below are read only by those names, so `~/.claude/CLAUDE.md` is not.
|
|
|
|
|
|
2026-10-20 13:51:34 -05:00
|
|
|
luxe reads, in order:
|
2026-10-17 12:08:30 -05:00
|
|
|
|
|
|
|
|
1. `~/.agents/AGENTS.md`, the file many people keep for every agent they use
|
2026-10-20 13:51:34 -05:00
|
|
|
2. `~/.config/luxe/agents.md`, for every project in luxe
|
2026-10-17 12:08:30 -05:00
|
|
|
3. `AGENTS.md` at the top of the repository
|
2026-10-20 13:51:34 -05:00
|
|
|
4. One `AGENTS.md` per folder down to where you started luxe
|
2026-10-17 12:08:30 -05:00
|
|
|
|
|
|
|
|
So a monorepo can keep shared rules at the root and package rules beside the code, and `luxe`
|
|
|
|
|
started in `packages/app` reads both. Nothing above the repository is read. Outside a repository,
|
|
|
|
|
only the folder you started in is, so an `AGENTS.md` in a parent folder never reaches a project it
|
|
|
|
|
was not written for.
|
|
|
|
|
|
|
|
|
|
The files are read once, when a session sends its first message, and every later request in the
|
|
|
|
|
session repeats that same text, which is what lets the provider reuse its cache. An edit reaches
|
|
|
|
|
the agent in the next session: `/new`, or resuming one. If you switch Git branches mid-session, the
|
|
|
|
|
agent is told with your next message.
|
|
|
|
|
|
Luxe 0.1.3: your sessions on your phone, joinable sessions, and nested AGENTS.md
- luxe remote puts the sessions on your computer in reach of your own phone or tablet over
Tailscale: write, steer, answer prompts, send photos, browse files, diffs and GitHub, with a
paired device and your own Tailscale login.
- luxe join lets another program on the same machine join a running session over the RPC protocol.
- An AGENTS.md in a subfolder reaches the model the first time it works there.
- Long sessions stay fast: no stall before each model call, lighter memory, cheaper drawing.
- A session is open in one Luxe at a time, web_search shares results across its phrasings, and a
grep glob starting with ! excludes.
The CHANGELOG has the full list.
2026-10-20 02:40:13 -05:00
|
|
|
### Folders the agent works in
|
|
|
|
|
|
|
|
|
|
An `AGENTS.md` in a folder below the repository's top, but not on the way to where you started,
|
|
|
|
|
joins when the agent first opens, writes or searches a path in that folder. It's added to that
|
2026-10-20 13:51:34 -05:00
|
|
|
tool result, once, and luxe shows **Following** and the file's path. The system prompt doesn't
|
Luxe 0.1.3: your sessions on your phone, joinable sessions, and nested AGENTS.md
- luxe remote puts the sessions on your computer in reach of your own phone or tablet over
Tailscale: write, steer, answer prompts, send photos, browse files, diffs and GitHub, with a
paired device and your own Tailscale login.
- luxe join lets another program on the same machine join a running session over the RPC protocol.
- An AGENTS.md in a subfolder reaches the model the first time it works there.
- Long sessions stay fast: no stall before each model call, lighter memory, cheaper drawing.
- A session is open in one Luxe at a time, web_search shares results across its phrasings, and a
grep glob starting with ! excludes.
The CHANGELOG has the full list.
2026-10-20 02:40:13 -05:00
|
|
|
change, so the cache holds. Ignored folders, such as `node_modules`, are skipped. If a rewind or a
|
|
|
|
|
compaction drops the file, it joins again the next time the agent goes there.
|
|
|
|
|
`LUXE_NESTED_INSTRUCTIONS=0` turns this off.
|
|
|
|
|
|
2026-10-17 12:08:30 -05:00
|
|
|
**Project context** lists every file a turn reads, and says whose rules each one carries:
|
|
|
|
|
**global**, **project** or **folder** context. Type `context` on the start screen and open it.
|
|
|
|
|
`enter` opens a file in your editor, or creates one from a template. The template's guidance is in
|
2026-10-20 13:51:34 -05:00
|
|
|
comments, which luxe removes and reports, so replace them with your own lines.
|
2026-10-17 12:08:30 -05:00
|
|
|
|
|
|
|
|
### Duplicates
|
|
|
|
|
|
|
|
|
|
A file the walk reaches twice is read once. That covers a symbolic link, such as
|
|
|
|
|
`~/.config/luxe/agents.md` pointing at `~/.agents/AGENTS.md`, and a file that is a byte-for-byte
|
|
|
|
|
copy of an earlier one. The context list shows the copy as *read once*.
|
|
|
|
|
|
|
|
|
|
Two files that say mostly the same thing are both read, because only you can say which sentence
|
|
|
|
|
should stay. Keep rules that apply everywhere in one global file, and the project's own rules in its
|
|
|
|
|
`AGENTS.md`.
|
|
|
|
|
|
|
|
|
|
```markdown title="AGENTS.md"
|
|
|
|
|
# AGENTS.md
|
|
|
|
|
|
|
|
|
|
- Run `pnpm test` before calling work done; `pnpm lint --fix` formats.
|
|
|
|
|
- Database changes go through a migration in `db/migrations/`, never by hand.
|
|
|
|
|
- The API returns errors as `{ "error": { "code", "message" } }`. Keep it that way.
|
|
|
|
|
- The current spec is in `docs/SPEC.md`. Read it before planning; skip it for small fixes.
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Keep it short
|
|
|
|
|
|
|
|
|
|
The file is part of every request, and a long one is followed less carefully, not more. For each
|
|
|
|
|
line, ask: would a capable model get this wrong without being told, and would that cost something?
|
|
|
|
|
Commands, pitfalls and conventions that differ from the usual pass. Directory layouts, dependency
|
|
|
|
|
lists and architecture overviews do not; the agent reads those from the code.
|
|
|
|
|
|
|
|
|
|
- A rule for one part of the tree goes in an `AGENTS.md` beside that code.
|
|
|
|
|
- A procedure the agent needs only sometimes goes in a [skill](skills.md).
|
|
|
|
|
- A plan, spec or design document stays a file. Name it in `AGENTS.md`, as above, and the agent
|
|
|
|
|
reads it when the work calls for it.
|
|
|
|
|
|
|
|
|
|
An `AGENTS.md` over 24,000 characters is cut off, with a note telling the agent to read the rest of
|
|
|
|
|
the file itself.
|
|
|
|
|
|
2026-10-20 13:51:34 -05:00
|
|
|
### What luxe removes
|
2026-10-17 12:08:30 -05:00
|
|
|
|
|
|
|
|
Two kinds of text are removed from `AGENTS.md` and skill files before the agent sees them, because
|
|
|
|
|
neither is visible to someone reviewing the file:
|
|
|
|
|
|
|
|
|
|
- Comments outside code blocks: HTML comments, `<!-- … -->`, and link definitions used as
|
|
|
|
|
comments, such as `[//]: # (…)`
|
|
|
|
|
- Invisible Unicode: tag characters, supplementary variation selectors, bidirectional overrides,
|
|
|
|
|
and soft hyphens and other marks that draw nothing, written as characters or as references
|
|
|
|
|
such as `‮`
|
|
|
|
|
|
2026-10-20 13:51:34 -05:00
|
|
|
A file that repeats one link label so often that luxe cannot check every definition is left out
|
|
|
|
|
entirely. For an `AGENTS.md`, luxe says what it removed or left out when it starts; a skill file is
|
2026-10-17 12:08:30 -05:00
|
|
|
cleaned without a notice.
|
|
|
|
|
|
|
|
|
|
## Where the project begins
|
|
|
|
|
|
2026-10-20 13:51:34 -05:00
|
|
|
luxe works on one project, found by walking up from where you started it:
|
2026-10-17 12:08:30 -05:00
|
|
|
|
|
|
|
|
1. Inside a repository (`.git`, `.jj` or `.hg`), the nearest folder with a `.luxe/` in it, up to
|
|
|
|
|
the top of the repository
|
|
|
|
|
2. Otherwise, the top of the repository
|
|
|
|
|
3. Outside any repository, the folder you are in
|
|
|
|
|
|
|
|
|
|
So `luxe` started in `crates/parser/src` opens the whole repository, with its sessions, plan and
|
|
|
|
|
reviews. The walk stops at your home folder. A Git worktree is its own project.
|
|
|
|
|
|
|
|
|
|
To keep a package of a monorepo separate, give it a `.luxe/`:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
mkdir -p packages/app/.luxe
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The package keeps its own sessions and still reads the `AGENTS.md` at the top of the repository.
|
|
|
|
|
|
2026-10-20 13:51:34 -05:00
|
|
|
Outside a repository, a `.luxe/` claims only its own folder. luxe writes one wherever it runs, so
|
2026-10-17 12:08:30 -05:00
|
|
|
starting it once in `~/.config` does not make `~/.config/herdr` part of that project.
|