Rules

Rules are Markdown files in a project that tell the agent how to work there: the commands to run, the style to keep, what to leave alone. A chat reads them from every folder of its project and follows them in every mode. An edit reaches a running chat at its next step.

Write rules for a project

1. Create AGENTS.md at the top of the project folder.
2. Write the instructions in plain Markdown.
3. Send a message: chats in the project follow the file from their next step.

# Working in this repo

- Run `npm test` before you call a change done.
- Never edit files under `vendor/`.

Which files a chat reads

A chat reads these files from the top of each of its project's folders, in this order:

• A file in a subfolder of rules/ is not read.
• Names match exactly: agents.md doesn't count.
• In a project with more than one folder, each folder's rules load under its own name, so the agent knows which folder a rule is for.
• A .mdc file loads whole. Its front matter (globs, alwaysApply) doesn't filter it.
• A rules file that is a symlink to a file outside the project folder doesn't load.
• A chat in its own worktree reads the worktree's copies.
• Lookout keeps its own files in .lookout/ out of git, but not rules/: commit it with the project.

Rules in subfolders and folders above

A subfolder can have its own AGENTS.md or CLAUDE.md (and its own .lookout/rules/ and .cursor/rules/). The first time a chat reads or writes a file under that subfolder, the agent gets the subfolder's rules once, as rules for the files under it, at its next step. From then on they stay with the chat while the file exists, across restarts, and an edit reaches the chat like any other rules file. Subfolders inside node_modules/ or a folder whose name starts with . don't count.

A chat that starts in a folder inside a git repository also reads the rules of every folder above it, up to the repository's top (the folder holding .git), when it starts. A chat in apps/web/ of a repo gets the repo's top AGENTS.md too. Lookout never reads folders above your home folder, or your home folder itself, this way, and a folder outside a repository has no folders above it that count.

Every rules file shares the same size limit; one past it says where to read the rest.

Rules for every project

Write rules that apply in every project and every chat, agents and subagents included, in ~/.lookout/AGENTS.md. They load ahead of the project's rules, on the same size limit, and an edit reaches a running chat at its next step like a project's. An @path import in this file doesn't load.

Rules from Claude Code and Codex

Lookout can also read the global rules files you keep for Claude Code and Codex. Turn on Use Claude Code and Codex rules and skills, first on Settings › Skills. It's off until you turn it on.

• Lookout reads these files where they are and never changes them.
• They load right after ~/.lookout/AGENTS.md. While the setting is on, Settings › Skills lists each file and skill it found, under the harness it comes from; a rules file reads Global rules, with its path on hover.
• Turning the setting on or off reaches a running chat at its next step, like an edit: the agent is told which files now apply, or that they no longer do.
• A project's own CLAUDE.md, in a subfolder or a folder above too, loads whether the setting is on or off.
• These global files load only as your own rules, never as a folder's: a chat in your home folder doesn't read ~/.claude/CLAUDE.md or ~/.codex/AGENTS.md as a subfolder's rules.
• The setting also brings in those harnesses' global skills folders, not the skills of Claude Code plugins (Skills from Claude Code and Codex).

Your rules on every machine

Signed in to your Lookout account, your rules for every project reach your other machines with Customize's sync: the text of ~/.lookout/AGENTS.md, the Use Claude Code and Codex rules and skills setting, and, from a machine where that setting is on, the Claude Code and Codex rules files it reads there.

• A machine that has its own copy of a file reads its own. One that doesn't reads the copy from your other machine, kept in ~/.lookout/rules-roamed/, and the agent is told which machine it comes from.
• An edit reaches your other machines within a few minutes, and their running chats at their next step, like any rules change. Deleting the file on the machine it came from removes the copies.
• A file over 64 KB, or one that looks like it holds a credential, stays on its machine; Customize says which.

Import another file

A rules file can pull in another file: write @ and the path, relative to the rules file, at the start of a line or after a space.

Follow the code style in @docs/style.md.

• The imported file loads right after the file that imports it.
• Imports nest up to 5 levels deep.
• Only files inside the project folder load: an import whose path, or the symlink it names, leads outside is skipped.
• An @path in a code span or a code block is not an import.

Size limits

All of a chat's rules load up to 60,000 characters together, the rules for every project first, then the working folder's, with no smaller limit per file: a long AGENTS.md loads whole. Rules past that are cut at a line break, and the agent is told where the rest is so it can read it. A file that no longer fits at all is left out with the same pointer.

When a change applies

A chat reads its rules when it starts. After that, a rules file you add, edit or delete reaches it at its next step, even in the middle of a turn: the agent is told the rules changed and gets the file as it is now, or only what changed in it when the file it last saw is still in the chat and the change is small. Only the files that changed are sent. A file the agent itself just wrote whole is named in one line instead of sent again. When the agent works in another worktree of the same repository, that worktree's copy of a rules file it already has counts as a change of it: the agent gets only what differs, or nothing when the copies match.

When rules are cut

Rules that load whole show nowhere: there is nothing to act on. When a chat's rules run past the limit, the context meter's panel says so under Rules: each cut file with the line the agent reads the rest from, or Left out. Point at a file for its path; click it to open it there.

Keep the agent out of files

Lookout reads three ignore files, in gitignore syntax: .gitignore, .lookoutignore and .cursorignore. Each can sit in the project folder or any folder under it. A deeper file wins over a shallower one, and a line starting with ! brings a path back.

An ignored path is one the agent's file tools won't read, edit, delete, list or search, and that @ mentions and the Files pane leave out. node_modules, .git, dist and .next are always ignored.

Use .lookoutignore for files git tracks but the agent should skip:

fixtures/recorded/
*.snap