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

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.

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:

cora -m ask

---

What each mode is good at

Ask: "Help me understand this"

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.

Plan: "Decide how to build this before building it"

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.

Code: "Make the change"

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.

Review: "Check this before it goes out"

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.

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.