Prompts and versions

An agent's prompt is its standing instructions. After this page you can read and edit one, see every version and who wrote it, undo a change, stop agents from editing it, and run a fixed version.

How versions work

A prompt is a Markdown document. Every save makes a new numbered version: v1, v2, v3. Nothing is overwritten. The newest version is live, and a new session loads it unless it is pinned to another version (see below). Older versions are kept.

A version records its number, the version it was based on, an optional note, when it was saved, and who wrote it:

• edited by a person, for example "edited by Ada".
• changed by the agent in a tool, for example "changed by the agent in Claude Code". A person still cosigns it, because the connection that ran the agent is theirs.
• imported, for a prompt that arrived with an import.

A prompt can be up to 128,000 characters. A note can be up to 500 characters. A prompt cannot be empty.

Read a prompt

Open Agents, choose an agent, and stay on the Prompt tab. The prompt shows as a formatted page. The line above it reads like "v16 · changed by the agent in Claude Code · 2h ago". When the prompt has more than one heading, a Contents list of them sits beside it.

Below the prompt, What each tool also receives lists any per-tool addendum, so you can see what a given tool actually gets. Each one reads "Added for Codex" or the name of its tool. An addendum is edited in the Tools tab, under Edit in Tools, and can be up to 8,000 characters.

Edit a prompt

You need edit access to the prompt: you own the agent, or it was shared with you with prompt edit access, which the Can edit preset and a Custom share can give.

1. On the Prompt tab, choose Edit. For an agent with no prompt yet the button is Write the prompt.
2. Edit the page in place. The toolbar has headings, bold, lists, links, code and tables. Choose View Markdown to edit the raw text, and Back to page to return.
3. Optional: fill in Note (optional) — why this change. The note is kept with the version.
4. Choose Save as v17, using the next number. The button stays disabled until something has changed.

Cancel asks "Discard your changes?" if you changed anything.

Note: The first time the editor saves a prompt it may tidy the formatting, for example table padding. When it does, the note fills in "formatting normalised by the editor". Later saves are stable. In History, Ignore formatting compares text without those differences.

If someone else saved first

If an agent or another person saved while you were editing, saving shows "This prompt changed while you were editing". It shows the difference between the version you started from and the new one. You can:

• Keep editing.
• Start again from the new version, losing your edit.
• Put my version on top, which saves yours as the next version. Their version stays in History.

The same rule protects against two devices overwriting each other, whether it is a person or an agent saving.

History

Choose History on the Prompt tab. A panel lists versions, newest first, with who wrote each, in which tool, when, and the note. Choose Older versions for more.

Select a version and use Show to switch between:

• What it changed: the difference from the version it was based on.
• Compare with current: the difference from the live version.
• Read: the version itself.

To undo, select an old version and choose Restore as v18. This saves the old text as a new version, with the note "Restored v12". History is only ever added to, so restoring never erases the versions in between.

People with view access can read History but not restore.

Agents can edit their own prompt

An agent's edit is live at once. There is no approval step. It needs a connection with the write permission and edit access to the prompt, and it is refused while the prompt is locked. The agent, through update_agent_prompt, must say which live version it started from, or the edit is refused as out of date. It is asked to say what it changed and why in a note, and you see the note in Activity.

Three things limit this:

• Every version is kept, and you can restore any of them.
• A daily limit. Agents may write 20 prompt versions per agent per rolling day. The limit stops a loop and is not a quota.
• Lock prompt. In an agent's Settings, under Prompt safety, turn on Lock prompt. Agents then cannot change the prompt, its tool profiles or its briefs. The Prompt tab shows "Locked — agents can't change this prompt". People with edit access still can.

Anyone you share an agent with decides for themselves whether to follow your changes. See the last section.

Note: The permission list on the connection screen says an agent can "propose prompt changes, which you approve". That wording is out of date. In the current app an agent's prompt edit goes live as soon as it is saved. Use Lock prompt if you want to stop it.

Run a fixed version (pinning)

By default a session loads the live version. You can run a fixed one instead. There is no button for this in the app. It is done in the files a checkout writes.

• In .omr/agent.json, set the agent's "prompt" to a whole number such as 3 instead of "live". A tool using omr-agent then loads that version. See omr-agent setup.
• When an agent checks an agent out into a workspace, it can pin a version. checkout_agent takes a pin, and the files it returns carry the version in both .omr/agent.json and the instruction file's load_agent call.
• load_agent itself accepts a version.

When a loaded version is no longer the latest, its header says "pinned" instead of "live". Asking for a version that does not exist is refused with "has no prompt version".

Agents shared with you

If an agent is shared with you, you run the version you accepted, not the live one, unless you turn on Follow updates (below). Accepting shows you the prompt first, because it will run as instructions in your own tools, with your access.

When the owner changes the agent, a banner appears: "Ada updated this agent · v14 → v16". You can then:

• Review changes, which opens History at your version.
• Update, to run the new version from now on.
• Turn on Follow updates to always run the newest. This is off by default and is your choice per agent.

The owner's own sessions run the live version unless a pin says otherwise. An agent's briefs are accepted the same way. See Memories and briefs.

Next

• Agents, sessions and attribution: sessions, profiles and whose name an agent writes under.
• Memories and briefs: the other half of what an agent knows.
• omr-agent setup: the files a checkout writes.
• Limits: all agent limits in one place.