Repository instructions
Tell every agent on a repository the same rules once. Standing instructions lead each new chat, Fast Forward instructions follow each continuation
A brief usually ends with the same rules: tests first, how to merge, what to reply. Repository instructions hold those rules per repository, so a brief says only what is new and Fast Forward continues with the rules of the repository it is pressed on.
Repository instructions are being rolled out and may not be on for your account yet. See Turn it off for what an account without them gets.
Two texts
| Text | What it does | Limit |
|---|---|---|
| Standing instructions | Lead the first message of every new chat on the repository, before your brief | 8,000 characters |
| Fast Forward instructions | Follow your continuation message every time a chat on the repository is fast-forwarded | 4,000 characters |
Both are Markdown. Set them on the repository's page under Environments, in the section Instructions. A preview beside the editor shows what is sent with the text as you type it, before you save.
Your account has a default for the standing text, under Settings, General. Your account's Fast Forward text is the continuation message you already have there, Forward task prompt (by default proceed).
Which text is in force
The most specific text wins, whole. Texts are never merged.
| Text | Order |
|---|---|
| Standing instructions | The chat's own, else the repository's, else the account default |
| Fast Forward instructions | The chat's own, else the repository's |
A repository without a standing text of its own uses your account default; Start from account default copies it into the editor when you want to extend it. Clearing a text makes that level inherit again.
A chat's own text is an override for that chat only. Set it over the API or MCP (PATCH /api/v1/chats/{id} with instructions, or update_chat): its Fast Forward text replaces the repository's on that chat, and its standing text is what that chat's agent reads in its file.
What Fast Forward sends
Three parts, in this order, each separated by an empty line:
- Your continuation message.
- The Fast Forward instructions in force for the chat.
- What the call passes:
messageover the API and MCP. The button in the app passes nothing.
In the app the button shows the composed message once, each part under where it comes from, and sends on Send. If the instructions changed between the look and the press, nothing is sent and you are asked to look again. Over the API and MCP, dryRun returns the same message and its parts without sending.
What a new chat starts with
The standing instructions in force, an empty line, then your brief. The chat is named after your brief, not after the instructions. A draft keeps your words as written and is led when it starts; a scheduled chat is led when it is scheduled.
Chats started from the app, the API, MCP, the CLI and automations are all led the same way. Redo opens the first message as it was sent, instructions included, for you to edit, and sends it as you leave it.
An organization agent's tasks are left alone: they are not led, get no file, and Fast Forward sends your continuation message alone on them. They follow their organization's instructions.
In the agent environment
n8v writes the texts in force for the chat to a file at the start of every turn, so an agent can read them even when its first message did not carry them, and a change reaches a running chat on its next turn.
| What | Value |
|---|---|
| File | ~/.n8v/instructions.md |
| Variable | N8V_INSTRUCTIONS_FILE, the file's absolute path |
| Pointer | One line in the agent's own instruction file names the file |
The file is in the home directory, outside the repository, so it can never be committed and needs no ignore rule. The variable holds the path and not the text: the text can change between turns, a running process's environment cannot, and a value in the environment reaches every child process and log. When nothing is set, the file is removed.
The variable is set when the agent's process starts. A chat that was already running when repository instructions were switched on has the file and the pointer from its next turn, and the variable from its next start.
Versions and who changed what
Every change is a new version with who made it, through what (the app, the API, an assistant) and when. History in the editor lists them and restores one into the editor; nothing is in force until you save. Each change is also written to your audit log as a policy change, with the version and the length, never the text.
Proposals
An assistant can propose a text instead of changing it (set_instructions with propose: true, or "propose": true over the API). Nothing is in force until you confirm it: the editor shows who proposed it, Review opens it in the editor where you can change it, Accept makes it live in your name, Dismiss drops it. Saving a text yourself withdraws a proposal that was waiting.
API and MCP
| What | API | MCP | Permission |
|---|---|---|---|
| Read the account default | GET /api/v1/instructions | get_instructions | chats:read |
| Read a repository's | GET /api/v1/repos/{owner}/{repo}/instructions | get_instructions with repo | chats:read |
| Read what is in force on a chat | GET /api/v1/chats/{id}/instructions | get_instructions with chat_id | chats:read |
| Change or propose | PATCH on the first two | set_instructions | chats:message |
| A chat's own override | PATCH /api/v1/chats/{id} with instructions | update_chat with instructions | chats:message |
| Look at what would be sent | POST /api/v1/chats/{id}/forward with dryRun | fast_forward with dry_run | chats:message |
Details and examples: Repository instructions in the API. whoami and GET /api/v1/me list the two tools with whether your connection may use them.
Turn it off
With repository instructions off for an account, everything is as before: Fast Forward sends your continuation message alone and at once, a new chat starts with your brief as written, no file is written, the endpoints answer 403 instructions_off and the tools are not listed. Texts you saved are kept and are in force again when it is switched back on.