> 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/working-with-cora.md).

# Working with CORA

Watch what CORA is doing while it works, let helpers handle big searches, and step back with revert or fork when you need to.

## Watching the work happen

While CORA works, it narrates in one-line rows.

```
● ran npm test                    12 lines  2.4s  ▸
✗ ran this-command-does-not-exist  1 line  exit 127  ▸
● read .../src/ui/app.js
● searched for "TODO" in src/ui
● updated the todo list 1/3
```

| Symbol     | Meaning                                                                               |
| ---------- | ------------------------------------------------------------------------------------- |
| ●          | Done, and fine                                                                        |
| ✗          | Something failed a command returned an error, a file could not be read                |
| ○          | Queued: the agent has asked for it, and it has not started                            |
| ◐          | Running now                                                                           |
| ■          | You stopped the turn with Ctrl+C                                                      |
| !          | The answer claims something the rest of the turn does not support worth reading twice |
| ▸          | There is output inside. Click the row, or press Ctrl+O for the newest one             |
| `12 lines` | How much output is hidden in there                                                    |
| `2.4s`     | How long it took (shown only when it is worth knowing)                                |

Similar actions in a row are folded into one, e.g. "Read 4 files", "Searched the web 3 times" and the number always matches what you find when you open it.

### The to-do panel

On longer jobs CORA keeps its own checklist, which sits above the prompt and updates as work proceeds. You can also see it any time with `/todo`.

```
☑ find where orders are validated
▸ add the deliveryNote field
☐ run the order tests
```

### The working line

While a turn is in flight, you see a line telling you CORA is busy and how long it has been going. If it is doing something in particular, it says what.

### Read the evidence, not the summary

When CORA says it is done, look at what it actually ran. Open the test row. Check the diff. A finished answer is a **report**, not proof, and CORA is built so that the proof is always one click away.

***

## Helpers

On bigger questions CORA sends a **helper** off to do the reading for example, searching two hundred files to answer "where is this used?". Helpers appear on a strip under the prompt while they work.

```
helper scout searching for callers of validateOrder
helper reviewer reading the diff
```

Press **1...9** to open one.

| What               | How                                                                  |
| ------------------ | -------------------------------------------------------------------- |
| **Watch one work** | Click its row, or press its number (1, 2, 3) on an empty prompt line |
| **Come back**      | Press **Esc**                                                        |

Inside, you see that helper's own conversation, everything it read, and the report it wrote, laid out exactly like the main one.

{% hint style="info" %}
**Helpers can only read.** They have no editing tools and cannot run commands. There is nothing a helper can do to your files.
{% endhint %}

Up to three run at once, so the strip stays readable. The limit is written into what CORA is told each turn rather than enforced by the CLI, so treat it as the normal case and not a hard ceiling.

Why they exist: a search across hundreds of files would otherwise fill your conversation with file contents just to produce a five-line answer. The helper reads all of it; your conversation only receives the answer. That keeps the conversation useful for longer.

***

## Undoing things

CORA gives you three different ways to step back. They do different things, and picking the right one matters.

| You want to...                      | Use                  | What it touches                       |
| ----------------------------------- | -------------------- | ------------------------------------- |
| Go back to an earlier prompt        | Ctrl+R, or `/revert` | Your files, the conversation, or both |
| Keep the conversation but branch it | `/fork`              | Nothing on disk                       |
| Start completely fresh              | `/new`               | Nothing on disk                       |

### Revert: undo the last turn's file changes

Press **Ctrl+R**, or type `/revert`. A picker opens listing every prompt in this conversation, with the files that turn changed beside it. It takes no argument you choose the point on screen rather than counting turns.

**Nothing moves while you look.** The picker shows you what a rewind would put back before you commit to it, and it takes two steps:

{% stepper %}
{% step %}

## Pick the prompt

Use ↑↓ to move, enter to continue, or esc to close. Nothing on disk or in the conversation has moved yet.
{% endstep %}

{% step %}

## Choose what comes back

Restore code and conversation, or restore conversation only. Enter confirms, esc goes back a step. The code choice is only offered when that turn actually changed files.
{% endstep %}
{% endstepper %}

**Nothing is destroyed either way.** A rewind forks the conversation rather than truncating it, so no message is deleted and there is no staged state left over to undo. Both the original and the rewound conversation stay in your history.

{% hint style="info" %}
**Restoring code needs a git repository.** File snapshots are taken with git, so in a folder that is not a repository there is nothing to put back, and only the conversation can be rewound. CORA says so plainly rather than claiming it worked.
{% endhint %}

What the picker looks like:

```
Rewind to an earlier prompt

›  fix the duplicate order bug (2 hours ago)
   src/api/orders.js +18 -4
   add the deliveryNote field (an hour ago)
   src/api/orders.js +6 -0  test/orders.test.js +22 -0

↑↓ move · enter continue · esc cancel
```

Pick a prompt and press enter, and the second step asks what to put back. Restoring code overwrites the listed files with the contents they had before that prompt ran, so read the file list before you confirm. Named checkpoints (`/checkpoint`, `/checkpoints`, `/restore`) are built but not switched on in this release; the picker is the way back for now.

### Fork: keep both versions of a conversation

`/fork` makes a copy of the conversation and opens the copy. The original is untouched, and both show up in your history. Use it when a conversation has gone somewhere useful, and you want to try a different direction without losing the first one. Forking copies the *conversation*, not your files.

### And of course: git

None of the above replaces your own version control. Commit before you start something big CORA reverting a turn and you reverting a commit are different tools for different depths of mistake.