Instructions

Project and global instructions loaded at startup.

Docs on GitHub

An AGENTS.md file holds standing instructions for the agent: coding conventions, package managers, framework rules, things to always or never do. zot loads them at startup and appends them to the system prompt. No file is created or required; zot only includes the ones that already exist.

Load order

Global instructions in $ZOT_HOME/AGENTS.md are loaded first. Then zot walks from the filesystem root down to the current working directory and loads the first matching instruction file in each directory. This includes ~/AGENTS.md when the working directory is inside your home directory. Later files are more specific and may override earlier ones.

  • $ZOT_HOME/AGENTS.md (global, applies everywhere)
  • <filesystem-root>/AGENTS.md
  • <ancestor>/AGENTS.md
  • <cwd>/AGENTS.md (closest to cwd wins on conflicts)

Per directory, zot reads the first of AGENTS.md or AGENTS.MD it finds. Empty files are skipped. Changing the working directory reloads the set for the new cwd.

Disable for one run

Pass --no-context-files or -nc to skip discovery and loading of every global and project AGENTS.md file for that run. The files are not read, appended to the system prompt, or listed in startup context.

Startup visibility

Enable show loaded resources at startup in /settings to list loaded context paths, extensions, and user-installed skills in compact Context, Extensions, and Skills sections above the transcript. Built-in skills are omitted. The setting is off by default, and the lists are not sent to the model or stored in the session transcript.

$ZOT_HOME defaults

  • All platforms: $XDG_STATE_HOME/zot when XDG_STATE_HOME is set.
  • macOS fallback: ~/Library/Application Support/zot.
  • Linux fallback: ~/.local/state/zot.
  • Windows fallback: %LOCALAPPDATA%/zot.

Only AGENTS.md

zot reads instruction context from AGENTS.md only. It does not load CLAUDE.md or other vendor instruction files. (The Claude- and agent-compatible layouts zot understands are for skills, under .claude/skills/ and .agents/skills/, not for instructions.) If you keep rules in a CLAUDE.md, point an AGENTS.md at it or copy the content over.

Example

AGENTS.md
# Project rules

- Use the package manager that matches the lockfile.
- Never start the dev server; run typecheck, lint, and build instead.
- Keep answers short and substantive.
- Do not use em-dashes in any text you write.

Reach for AGENTS.md when you want rules that travel with a repository and apply to every session. Reach for SYSTEM.md when you want to replace zot's core identity outright.