Troubleshooting and FAQs

Fix common problems, answers to frequent questions, and a glossary of terms.

Troubleshooting

Always start with cora --doctor. It reports what it can see and names the fix.

Problem	What it means	What to do
"The Toolbox is not running"	The CodeMate Toolbox app is closed	Open it and leave it open
"You are not signed in"	The Toolbox is running but signed out	Open the Toolbox and sign in
"Update the Toolbox"	The Toolbox is too old for this version of CORA	Update it from app.codemate.ai/download
cora is not recognised	Your terminal was open before the Toolbox was installed	Close it and open a new terminal window; if it still fails, reinstall the Toolbox
Nothing happens when I start it	CORA needs a real terminal	Run it in a terminal, not through a tool that captures the output
It says it cannot edit a file	You are in a read-only mode	Press Shift+Tab until the prompt footer says code
It refuses to write AGENTS.md	Either one exists, or you are in a read-only mode	Rename yours, or switch to code mode
A mode change looks ignored	Something is still running from an earlier start	Quit cora fully and start it again
A permission I set is still asking	Permissions are read when the agent starts	Quit cora and start it again; /settings says so while the file and the running agent disagree
A rewind offers no code option	The folder is not a git repository, or that turn changed nothing	File snapshots need git; the conversation can still be rewound on its own
Answers come back empty	The configured model may be unavailable	Check with whoever set up your deployment
A new skill is not there	Skills load at start-up	Restart cora; /skills lists what is waiting
A new workflow is missing from the / menu	The menu is built at start-up	Type its name anyway; it works; it appears in the menu next time
The web search never finds anything	It may need approving, or be blocked on your network	Check you approved it, and ask your IT team about outbound access
Everything hangs	Something is stuck	Ctrl+C to quit, restart the Toolbox, try again
Odd characters appear when I type	A previous program left the terminal in a strange state	Close the terminal window and open a new one

Getting more detail. Run cora with --verbose, --debug, or --trace to put more detail in the log file. The log file's location is printed when something goes wrong, and it lives in ~/.cora-cli/logs/.

---

Frequently asked questions

Which mode should I use for normal work?

code. It can look at the project, make the change, and run the check in one go. Put the failing command, the relevant files, what you expect, and the check you want run into your first message.

Will CORA change my files without telling me?

No. Every edit and every command stops and asks, and shows you what it wants to do. The three read-only modes cannot do either at all.

It said it was done. Does that mean it worked?

Not on its own. A completed answer is a report, not proof. Open the test row, read the diff, run the thing yourself. For anything consequential, switch to review mode and have the change audited.

Can I use it on code I did not write, or on someone else's pull request?

Yes. Review mode audits any change, whoever wrote it. Point it at the range you care about and ask for findings with file and line.

How do I stop it partway through?

Ctrl+C once. That stops the turn and refuses anything it was waiting on. A second Ctrl+C quits cora.

It is doing the wrong thing. Should I start over?

Usually not. Stop it, say precisely what is wrong and what you want instead, and carry on. A precise correction keeps all the useful context. Start over only when the whole direction was wrong.

Can I make it stop asking permission every time?

For specific, narrow things, yes use /settings and add rules for the safe command families you use constantly. Keep everything else on ask. There is no single switch that turns approvals off, deliberately.

Why did it ask about a command I thought was safe?

Because it cannot know your intent. A command that is safe in one repository deletes something important in another. Approving takes one keypress; the alternative is not recoverable.

Does it remember my project between conversations?

Not by itself. Put what it should always know in AGENTS.md (or use /init to write one), and put your team's standing constraints in rules. That is what makes knowledge survive a /new.

How do I stop it repeating a mistake?

Write the correction as a rule. "Always run this test command"; "never touch this folder". It is sent with every message from then on.

It has forgotten something from earlier in the conversation. Why?

Long conversations get compacted folded into a summary, and a summary loses detail. /context tells you if that has happened. For anything you must not lose, write it into a file rather than leaving it in the conversation.

Can I run two things at once?

Open cora in two terminals, in two different folders. Keep unrelated work in separate conversations rather than switching topics inside one.

Is my code being uploaded anywhere?

Your conversations are stored on your own machine. CORA reads files from your project and sends what is needed to answer through the Toolbox you signed into. It never publishes your repository anywhere, and it never pushes or deploys.

How do I ask for a security review?

Use review mode on the actual change, and name the areas you care about: authentication, permissions, secrets, input validation, database access, logging, and missing tests. Review reports; it does not fix. Take the findings to a code-mode conversation.

Can I trust it with payments, logins, or anything regulated?

It can help you build and review such a change, but it is not a substitute for your own engineering judgement, your security review, your tests, or your release process. Plan first, review after, and keep the merge decision yours.

Which files should I commit?

Anything in <project>/.cora-cli/ that your team should share: rules, skills, workflows, outside-tool connections, plus AGENTS.md. Your personal ~/.cora-cli/ folder is yours and is never part of the repository.

---

Glossary

Term	What it means
Approval	The prompt asking you to allow one file edit or one command. y allows, n refuses.
Checkpoint	A named point you can bring your files back to. A bookmark, not a backup.
Compact	Folding the older part of a conversation into a summary to make room.
Context window	How much of a conversation CORA can hold in mind at once. /context shows how full it is.
Conversation	One thread of work, saved on your machine, resumable later.
Fork	A copy of a conversation, so you can try two directions and keep both.
Helper	A read-only assistant CORA sends off to search or review. It cannot change anything.
MCP server	A connection to a tool outside your project an issue tracker, docs, a database.
Mode	ask, plan, code, or review. Decides what cora is allowed to do. Shift+Tab cycles.
Project/workspace	The folder CORA is working in.
Revert	Rolling your files back to how they were before a turn.
Rule	A markdown file sent with every message, a standing instruction.
Session	The live connection behind a conversation. It restarts; your conversation does not.
Skill	A reusable playbook CORA can reach for when the job matches.
Slash command	Anything you type starting with /, handled by CORA itself and never sent to the model.
Toolbox	The CodeMate app that signs you in and connects CORA to the model. It has to be running.
Tool row	One line in the conversation describing something CORA did. Click it to see the output.
Turn	One message from you and everything CORA does in response.
Workflow	A markdown file holding a procedure, run by typing its name as a command.

---

Note: If something on your screen does not match what you read here, run cora --doctor and check your version first.