Navigation
ELOWEN · Documentation

Last updated: October 27, 2026

Browse documentation · Give a Project its own instructions
Computers, terminal and Git

Give a Project its own instructions

A context file is an AGENTS.md or CLAUDE.md in the root folder of a Project, and its contents join the model's instructions when a conversation in that Project starts.

Use it for what holds for all work in that Project, such as coding conventions or the test command. For a procedure you want to reuse in other conversations, write a skill instead.

Where the file is loaded

Context files load automatically; no setting turns them on.

  • Your own chat reads the file of the Project the conversation runs in. On the web, switch it with the picker in the chat header; in the CLI, /project does it, while /cd only moves the terminal's own folder.
  • A new web conversation starts in your default Project, the first one in your Project order.
  • A host conversation that names no Project uses the registered Project its working directory sits in.
  • A managed Project reads the file from the Project's folder inside its environment. A stopped environment is not started just to read it, so the conversation opens without the file.
  • A chatbot account reads the file of the one Project it is bound to, and nothing else. That is how a chatbot gets its persona, so anything in that file reaches the visitors who talk to it.
  • Only the Project root counts. A file in a folder above the Project is never loaded, and a working directory outside every registered Project loads nothing. In a linked Git worktree of a registered Project, the root is the worktree's own top-level folder.

Delegated sub-agents started from your own chat read the same file, forks and nested sub-agents included. Other accounts and shared channels such as Teams or Discord do not.

Add a context file

  1. Create the file in the root folder of the Project, using one of these exact names.
  2. Write the instructions that apply to all work in that Project.
  3. Start a conversation in the Project. Chetty adds the file to the model's instructions while the conversation is set up.

When several of these exist, only the first one in this order is loaded:

  • AGENTS.override.md
  • AGENTS.md (or AGENTS.MD)
  • CLAUDE.md (or CLAUDE.MD)

A file larger than 256 KiB is not loaded at all. A context file does not create a Project, change the working directory or grant access to tools or files; your account's permissions still apply.

Keep it short with rule files

Every conversation in the Project pays for a long root file. Keep the root to what is always true and move the rest into rule files: Markdown files under .elowen/rules, subfolders included.

A rule file names the files it belongs to in its frontmatter:

---
paths:
  - "src/api/**/*.ts"
  - "tests/api/**/*.ts"
---
# API rules
- Validate endpoint inputs.
- Update the contract tests.

Chetty attaches that rule file when it reads, writes or edits a matching file, starting with the next model step of that turn. The patterns use *, ** and ?, and several patterns are alternatives. Without frontmatter it is unconditional and joins the root file at the start of the conversation.

Instructions for one folder can sit in an AGENTS.md of that folder, for example src/payments/AGENTS.md. Chetty attaches it when it works with a file in that folder or below it, and it never replaces the root file.

A rule file that fails to load is written to the daemon log and never replaced by a broader one:

  • Frontmatter that is invalid, or that names anything other than paths, keeps the file out entirely.
  • A rule file over 256 KiB is refused whole. Instructions are never shortened.
  • A rule file that points outside the Project through a link is refused.
  • Only work on files counts. Mentioning a path in a message, listing a folder or running a shell command does not attach a rule file.

When changes take effect

The root file is read once, when the conversation is set up, and stays the same for every message after that. Identical instructions between messages keep replies fast and cheaper.

An edit to the root file takes effect when the conversation is set up again: in a new conversation, after switching the model, after Chetty restarts, or after the conversation has been idle for about 30 minutes.

An attached rule file or nested AGENTS.md stays in the conversation's history, and a restart does not attach it twice. After the conversation is summarized it can be attached again when the file is next touched.

When the file itself changes, the new content arrives the next time a matching file is touched, marked as replacing the earlier version. Nothing is watched in the background, so a change never reaches a conversation on its own.

If it does not work

  • Nothing changed after an edit. The root file is read once per conversation. Start a new conversation, switch the model or restart Chetty; a rule file takes effect the next time Chetty touches a matching file.
  • The file is ignored. Check the exact name and that the file sits in the Project root. A file in a parent folder is never loaded.
  • Only your own chat sees it. Context files load for your own chat, its delegated sub-agents and a chatbot account bound to the Project, not for other accounts or shared channels.
  • A rule file never loads. Check that the file sits under .elowen/rules, that its frontmatter holds only paths, and that its patterns match the files Chetty actually works with.