> For the complete documentation index, see [llms.txt](https://docs.codemate.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codemate.ai/cora-cli/writing-effective-prompts.md).

# Writing Effective Prompts

How to write a good request, use the prompt line, and attach files, images, and command output.

## Writing a good request

The biggest difference between a great result and a frustrating one is the first message. Treat it as a **work order**, not a chat opener.

A good request has five parts. You will not always need all of them.

| Part                      | Example                                                              |
| ------------------------- | -------------------------------------------------------------------- |
| **The goal**              | "Add an optional delivery note to the order-create flow."            |
| **The evidence**          | "`@src/api/orders.js`, and the failing output in `@notes/error.txt`" |
| **The boundary**          | "Do not change any response field other than `deliveryNote`."        |
| **The pattern to follow** | "Validate it the way `@src/api/customers.js` does."                  |
| **How you will check it** | "Run the orders tests and show me the output."                       |

Compare:

{% stepper %}
{% step %}

## Add delivery notes

`Add delivery notes`
{% endstep %}

{% step %}

## Add an optional delivery note field

`Add an optional deliveryNote field to the order-create flow. Follow the validation pattern in @src/api/customers.js. Do not change any other response field. Add one test alongside the existing order tests and show me the result.`
{% endstep %}
{% endstepper %}

The second takes twenty seconds longer to type and saves an afternoon.

### Six habits that pay for themselves

{% stepper %}
{% step %}

## Attach, do not paste

`@src/api/orders.js` beats pasting the file. CORA reads the real thing, and your conversation stays readable.
{% endstep %}

{% step %}

## Point at one good example

"Follow the pattern in this file" beats three paragraphs describing your style.
{% endstep %}

{% step %}

## Say what must not change

A boundary is easier to respect than a preference.
{% endstep %}

{% step %}

## Ask for the evidence

"Show me the test output" turns a claim into a fact.
{% endstep %}

{% step %}

## Ask one coherent thing

One well-scoped request beats five fragments.
{% endstep %}

{% step %}

## Say when you do not want it to guess

"Mark anything you are unsure about as an open question rather than inventing it" is a sentence worth keeping on your clipboard.
{% endstep %}
{% endstepper %}

### When the answer is not what you wanted

Do not start over with a vague complaint. Point at the gap and supply what's missing:

```
The plan is missing the rollback steps and the error cases. Add
those two sections using @docs/migration-policy.md; leave the
rest as it is.
```

A precise correction keeps everything useful that came before it.

***

## The prompt line

The box at the bottom is where you type. It does more than it looks like.

| Key                   | What it does                                                 |
| --------------------- | ------------------------------------------------------------ |
| **Enter**             | Send the message                                             |
| **Ctrl+J**            | Add a new line **without** sending, for multi-line requests  |
| **↑ / ↓**             | Bring back something you typed earlier                       |
| **Tab**               | Complete a `/command` or an `@path` you have started typing  |
| **Ctrl+A** / **Home** | Jump to the start of the line                                |
| **Ctrl+E** / **End**  | Jump to the end of the line                                  |
| **Ctrl+← / →**        | Move a whole word at a time                                  |
| **Ctrl+C**            | Stop the turn that is running. Press it again to quit `cora` |

**Typing `/`** opens the command menu above the prompt, showing six matches at a time, filtered as you type. Press **Tab** to complete the first one. The menu disappears once you type a space, so it never sits on top of an argument you are writing.

**Typing `@`** starts a file path. Keep typing and press **Tab** to complete. The attached file appears as a neat chip rather than a long path.

***

## Attaching files, images, and command output

### Files

Type `@` and start the path; press **Tab** to complete it.

```
explain @src/auth.js
compare @src/api/orders.js and @src/api/customers.js
```

You can attach several files in one message. One attached file is capped at 64 KB, and all the attachments in a message at 192 KB together anything over either cap is refused by name rather than quietly truncated.

### Dragging files onto the window

Drag a file from your file manager onto the terminal window. CORA turns the path into an attachment automatically.

* Several files at once works; each becomes its own attachment.
* A path with a space in it is handled for you.
* If the path does not exist, nothing is swallowed: it stays as ordinary text.

### Images and screenshots

CORA can look at pictures a screenshot of a broken layout, a photo of an error on someone else's screen, a design mock-up.

```
What is wrong with this layout? @screenshot.png
```

* Supported: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`
* Maximum size: **5 MB** per image
* Take a screenshot and press **Ctrl+Y** to paste it straight from the clipboard; no need to save it first. This works on Windows, macOS, and Linux on Linux it needs **wl-clipboard** or **xclip** installed.

If the model in use cannot read images, CORA tells you **before** sending, so you never pay for a turn that was never going to work. Your text still goes; only the picture is dropped.

The conversation records the picture's name, size, and dimensions (`shot.png 41.2 KB 1920×1080`) rather than the image data, so your transcript stays readable.

### Piping command output in

You can send `cora` the output of another command:

```bash
git diff | cora --run "review this change"
npm test 2>&1 | cora --run "why did this fail?"
```

The piped text arrives as its own separate block, so CORA can tell your instruction apart from the material it is acting on. The limit is 256 KB; above that, CORA refuses and asks you to narrow it rather than quietly cutting half of it off.