> 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/modes.md).

# Modes

CORA is always in one of four modes. The mode decides **what it is allowed to do**, not just how it talks.

**Press Shift+Tab to cycle through the modes.** Type `/mode` to see the list with the active one marked.

| Mode                     | What it is for                                   | Can it change your files?           |
| ------------------------ | ------------------------------------------------ | ----------------------------------- |
| **code** *(the default)* | Writing and changing code, running tests         | **Yes**, and it asks you every time |
| **ask**                  | Answering questions about the code               | No                                  |
| **plan**                 | Investigating, then writing a plan of what to do | No                                  |
| **review**               | Reviewing changes and reporting problems         | No                                  |

{% hint style="info" %}
The three read-only modes have no editing tool and no way to run commands at all. They cannot change a file even if you ask them to; they will say so and tell you to switch to code mode. This is not a polite refusal the capability is simply not there.
{% endhint %}

**Start in Ask if you are new.** Nothing it does can surprise you.

**The mode resets every time you start.** Every run of `cora` starts in **code**, and `/new` resets to code as well. A mode is *what you are doing right now*, not a setting you configure once. To start somewhere else:

```bash
cora -m ask
```

***

## What each mode is good at

<details>

<summary>Ask: "Help me understand this"</summary>

Use it before you touch code you do not know. The best questions are about *your* project, not about programming in general:

* Trace what happens when someone signs in, from the route to the database
* Why does `@src/auth/session.js` refresh the token twice?
* Which files would I have to change to add a "delivery note" field?

It can read files, search the project, and look things up on the web. It cannot edit, and it cannot run commands, so it can tell you what it believes, but it cannot *prove* a fix works. When you know what needs building, switch to code.

Ask CORA to push back, too. If your question contains a wrong assumption, it is meant to say so treat that correction as information, not as a refusal.

</details>

<details>

<summary>Plan: "Decide how to build this before building it"</summary>

Plan mode investigates and then writes you a plan: what to change, in what order, what could go wrong, and how to check it worked. It cannot edit code, and it cannot run commands.

Bring it trade-offs rather than a preselected answer:

```
We need per-customer credit limits. Constraints: the API must stay
backwards compatible, and we cannot change the orders table. What
are the two or three ways to do this, and which do you recommend?
```

Expect to be asked questions back. Plan mode asks about the decisions it genuinely cannot make for you, then writes the plan around your answers.

A plan worth having says all of this: the goal, the approach chosen and the ones rejected, the files affected, the error and edge cases, the commands that verify it, how to roll it back, **and what must not change.** Ask for the last one explicitly a plan that says what to leave alone is much easier to implement safely.

When the plan is good, **press Ctrl+X then i** to hand it straight to code mode, or switch mode yourself and say `implement the plan above`.

</details>

<details>

<summary>Code: "Make the change"</summary>

The normal mode for day-to-day work. It can read, edit, and run commands, and it asks before each edit and each command.

The single most useful habit: **tell it how you will know it worked.**

```
Fix the failing checkout tax calculation. Reproduce it first, fix
the shared calculation rather than patching one caller, add one
small test, then show me the test output.
```

That last clause turns a change that *looks* right into one you can check.

How CORA debugs: it runs your tests or a reproduction script, reads the error, and adds temporary logging where it needs to see more. It does not step through your code with a debugger. So give it the failing command or the failing test that is worth more than a paragraph describing the symptom.

</details>

<details>

<summary>Review: "Check this before it goes out"</summary>

Review reads changes and reports problems. It can read files and run read-only commands, but **it cannot edit.** That is the point: a reviewer that can quietly fix things is not a reviewer.

```
Review my uncommitted changes for correctness, security, and
missing tests. Report each finding as: how serious, which file
and line, what goes wrong, and how to fix it.
```

It reviews code *you* wrote just as happily as code CORA wrote. Running it on your own work before you open a pull request is one of the highest-value things it does it has no attachment to the change and no memory of why you wrote it that way.

Take the findings you agree with, switch to code mode, and ask for those fixes.

</details>

## Choosing the right mode for the job

Start from the job, not from the most powerful-looking option.

| If you need to...                                                           | Use        | A first message you can copy                                                                                                                                                                       |
| --------------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Understand unfamiliar code, or explain a failure, without changing anything | **ask**    | `Trace @src/orders/create.js from the route to the database. Explain how a duplicate order can be created. Cite the files and lines, and do not change anything.`                                  |
| Decide how to build something before building it                            | **plan**   | `Write a plan for adding a per-customer credit limit. Cover the files affected, the API and database changes, validation, how we roll it back, the test cases, and anything you are unsure about.` |
| Fix a bug or add a feature                                                  | **code**   | `Fix the bug described in @notes/bug-123.md. Follow the pattern in @src/api/orders.js, keep the public API unchanged, add a small test, and show me the test output.`                              |
| Check a change before merging it                                            | **review** | `Review my uncommitted changes for correctness, compatibility, security, and missing tests. Only report things you can point at, with file and line.`                                              |

A few common jobs and the path that works best:

| The work                                           | Do this                                 | Why                                                              |
| -------------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------- |
| A reproducible bug in one place                    | **code**, then **review** if it matters | Code can reproduce it, fix it, and run the test in one go.       |
| A small field, validation rule, or UI tweak        | **code**                                | Name the existing pattern to follow and the check you want run.  |
| A multi-file feature you already understand        | **plan → code → review**                | A plan you have read first saves rework.                         |
| A vague, cross-cutting change                      | **ask** or **plan** first               | Resolve the unknowns before anyone writes code.                  |
| Anything touching payments, logins, or permissions | **plan → code → review**                | Slow down deliberately, and get the independent read at the end. |