AGENTS.md

AGENTS.md is a file you place at the root of your project to describe conventions, constraints, and any other guidance the agent should follow when working in that repository. Kodik finds these files automatically and injects their contents into the system prompt before every task.

Related feature: Rules let you set instructions through the IDE UI without creating files manually.

File loading order

Kodik walks the directory tree from the project root down to the current working directory. In each directory it looks for the following files in priority order:

1. AGENTS.override.md — loaded first if present
2. AGENTS.md — loaded if AGENTS.override.md is absent
3. Files listed in kodik.project_doc_fallback_filenames — checked next

Once one file is found in a directory, the others are not checked for that directory.

Global instructions

The file ~/Documents/Kodik/agents.md (or ~/Documents/Kodik/AGENTS.md) applies to all projects. Its content is prepended to the project instructions in the prompt.

Project root detection

To determine the boundaries of your project, Kodik searches upward for a root marker — .git by default. The directory walk starts from the found root. If no marker is found, only the current working directory is used.

Settings

Setting	Default	Description
kodik.project_doc_max_bytes	32768	Maximum combined byte size of loaded instructions. Set to 0 to disable AGENTS.md discovery entirely.
kodik.project_doc_fallback_filenames	[]	Additional filenames to try in each directory when neither AGENTS.md nor AGENTS.override.md is found.
kodik.project_root_markers	[".git"]	File or directory names used to locate the project root. Use an empty list to check only the current working directory.

What to put in AGENTS.md

AGENTS.md is a good place for:

• Build, test, and run commands
• Code style and file organization conventions
• Constraints: what the agent must not touch or delete
• Architecture overview and key dependencies

Tip

AGENTS.override.md is useful when you need to temporarily override instructions from AGENTS.md in the same directory without touching the main file.

Security

Files are truncated if their combined size would exceed kodik.project_doc_max_bytes. Files with invalid UTF-8 produce a warning but do not block the task from starting.