Prompt templates

Prompt templates let you save a prompt you keep rewriting from memory under a name, turn the parts that change into fields you fill in, and run it again in any session.

Your library

Settings → Prompts shows your templates as a list, one row each. Select a template, or move through the list with the arrow keys and press Enter, and it opens in the side panel on the right. There you can read the prompt and see its fields with their defaults. The buttons next to it are Edit, Copy and Delete, plus Propose to organization… when one of your organizations accepts prompts. Small buttons beside the Your library heading search your prompts, export your whole library to the clipboard, and start a New prompt. While your library is empty, New prompt is the list's only row.

The editor only appears when you ask for it, with New prompt or Edit. Cancel and Save sit at the top of the editor, and when you save, the template opens in the read view.

Writing one

Go to Settings → Prompts and press New prompt (the plus beside the Your library heading). Give it a name and write the prompt. Wherever a value should go, put a field in, which shows as a small chip in the text. You can do that in three ways:

• Type {. A list of your fields opens at the cursor. Keep typing to narrow it, then press Enter or Tab to put one in, or Esc to close the list and keep what you typed.
• Click or drag a field chip. Your fields are listed under the prompt, next to Type { or drag a field in. Click one to put it at the cursor, or drag it to where it belongs. A chip already in the prompt can be dragged somewhere else the same way.
• Name a new one. If what you type after { is not a field yet, the list offers New field "…". Pick it and the chip goes in, and the field is added to the list underneath for you to give a kind and a label.

A chip turns amber when something is wrong with it, for example Not set up as a field yet. Hover over it to see why.

Behind the chips the prompt is plain text, with each field written as {{name}}:

Review the changes on {{branch}} and tell me what you would change,
focusing on {{focus}}.

Press Edit as text above the prompt to write it that way yourself, and Edit with fields to go back to chips. Anything you type or paste in that form becomes a chip too. If the text uses a name that is not set up as a field, Plexus offers to add it for you.

Under the prompt, the Fields tab lists your fields and Preview shows what the prompt turns into with every field at its default.

Fields

Each field has a kind, and the kind is what makes a template better than a text file you keep open in another window.

The last two are the ones only Plexus can offer, because it is the thing holding your worktree and your git state.

A field can be marked needed, and then the prompt cannot run until it is filled.

Turning a paragraph on and off

A checkbox is not used like the others. Instead of putting a value somewhere, it wraps a part of the prompt. Pick a checkbox from the { list, where it shows as Show only when …, or click its chip, and it goes in as a pair of chips, if deep and end deep, with the cursor between them. If you select some text first, the pair wraps that text. New checkbox section "…" in the { list makes a new checkbox and its pair in one step.

As text, the same thing reads:

Review the changes on {{branch}}.
{{?deep}}
Go through every file line by line. Do not summarise.
{{/deep}}

With the box ticked, the middle lines are in the prompt. With it clear, they are gone — not blanked, gone. A field that only appears inside a section that is switched off is not needed, even if you marked it so.

Running one

In a new session. Open New session and a Template field appears above the branch fields. Pick one, fill it in, and create the session. Changed your mind? The ✕ next to the field, or No template at the top of its list, takes the template back off. The rendered prompt is waiting in the terminal when the agent comes up — including when you have auto-start switched off, in which case it waits until you press Start.

In a session already running. Insert prompt in the footer of the Agent tab does the same thing for the session you are in.

Either way Plexus types the prompt into the terminal and leaves it there. It never presses return for you: you read what it wrote and send it yourself.

Starting from a session that already worked

The prompt worth keeping is usually one that already did the job. Save as template… in a session's ⋯ menu takes that session's opening prompt and opens it in the editor, ready to change.

It works on a session that is stopped or archived, which is usually when you know the prompt was worth keeping.

Where a template lives

Every template is filed under one of five places, and the list shows them all together with a badge saying which — and since version 0.21.0 the New session and Insert prompt pickers show the same badge on every row. There is no override chain: two templates with the same name are two templates.

Templates a repository brings with it

A project can keep prompts in its own .plexus/templates/ folder, so everybody who clones it gets the same ones. Each is a markdown file with a small JSON block at the top:

---
{
  "title": "Fix the failing test",
  "description": "What we ask for when CI goes red.",
  "variables": [
    { "name": "test_name", "type": "text", "required": true }
  ]
}
---

The test `{{test_name}}` is failing. Work out why and fix it.

These work with no account and no plan, and they are the one kind that never leaves your computer — Plexus has no way to send one.

If a file cannot be read, Plexus says which file and carries on with the rest of the list. It never quotes the contents back at you.

To turn them off, use Use prompt templates committed to the repository — see Settings. It is on by default, and you can set it per project. It is not the same switch as the one for repository scripts: that one is about code running, this one is about prose arriving.

Keeping them on every machine

Templates you save are kept in your Plexus account, so they follow you to every machine you sign in on. Nothing is sent until you say so. (An organization's prompts are not part of this: they reach each machine from the organization directly, and one of yours reaches the organization only when you press Propose to organization… on it — see Prompts your organization publishes.)

Press Show me what this machine would send… and Plexus lists every prompt that would leave — each one in full — alongside anything staying here and why. Only then does the first one go.

Afterwards, the Sync prompts row under Sync on Settings → Prompts tells you when it last checked, which machine wrote last, and how many prompts are still waiting to go. That is deliberate: "you have not saved anything" and "we could not reach your account" should never look the same.

What a plan changes, and what it does not

Saving a prompt to your account needs a plan — an individual plan, or a seat on an organization's.

Everything else does not, and never will. If a plan ends:

• every template you already have keeps listing, running, copying and exporting, on every machine that has it;
• you can still delete any of them, and still delete every template we hold;
• templates a repository committed keep working exactly as before, because they never needed an account in the first place.

The reason that works is that a full copy of your library is on your own disk. Plexus reads from that copy, not from us — ours carries it between your machines and is never the only one.

Related

• Sessions — where a template's prompt ends up.
• Lifecycle hooks — the other thing a repository can bring with it.
• Settings — including the switch for repository templates.
• Prompts your organization publishes — the fifth place a template can live, and how an organization's revisions reach you.