> 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/troubleshooting-and-faqs.md).
# Troubleshooting and FAQs
Fix common problems, answers to frequent questions, and a glossary of terms.
## Troubleshooting
{% hint style="info" %}
**Always start with `cora --doctor`.** It reports what it can see and names the fix.
{% endhint %}
| 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](https://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 `/.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.*