Troubleshooting

The problems people run into most, and the quickest way out of each.

First: monixcode doctor

monixcode doctor

It checks the installation, whether the server answers and whether it is the version you installed, whether the provider you chose has credentials, and where the logs are. If it prints a problem, fix that first. If it does not, look at the logs:

monixcode logs            # server and interface
monixcode logs server -f  # follow the server's log

The server does not start, or the interface cannot find it

• monixcode server status says whether one is running and whether it matches your installed version.
• After an update or a reinstall, an old server can still be running. Run monixcode restart.
• Watch it start in the foreground with monixcode server run; the reason it stops is printed there.
• A second instance on another port needs MONIXCODE_PORT; see Environment variables.

It says the licence is required (402)

The server answers with a licence error when this machine is not activated, the seat was released, or the licence is bound to another machine (the message says so). The message also names two other cases: an online licence that could not reach the licence server for a few hours stops until the network is back, and nothing is wrong with the licence itself; and a build that is newer than your update window is refused — reinstall the version you own, or extend the window. Open monixcode and sign in, or use monixcode license relogin after a monixcode logout. To use the licence on a different machine, monixcode license move. Your data is still readable in this state: monixcode export works without a licence. See Licence & updates.

“Denied: read-only mode”

You are in Read only mode, or in Plan mode. In both it may read and search but not write or run commands. Cycle the mode with Shift + Tab or /mode; in plan mode, approving the plan switches writing on. See what stops a tool.

“Writing to .monixcode/ is not allowed”

The .monixcode folder of a project holds Monixcode's own project data, and the agent must not change it — the memory only changes through you. The one exception is .monixcode/scratch/: that is where temporary files and tool caches go, and it is the only writable part. If the agent needs scratch space, it should use that or a system temporary folder.

The same rule covers Monixcode's settings and the memory: change them in the settings window and the panels, not through the agent. See What the agent cannot touch.

“Outside all project scopes”

A path outside the project is refused until you grant it. Approve the agent's request when it asks, or add it yourself with /paths allow <folder>. A path you denied stays denied even when everything else is allowed.

It keeps asking for approval

In the default mode every shell command asks. Answer a for “allow this command from now on”, or add a command with /allow. For an unattended run, use Auto — and read Permissions & safety first.

Update problems

• monixcode update --check reports without installing.
• “Not covered” means your update window has closed. The version you have keeps working; you can extend the window.
• After an update the server restarts on the new build. If the interface was open, quit it and start monixcode again.
• If it says the server did not come back, start it with monixcode server start and check monixcode logs server.

It uses many tokens

Start with /context: it shows where the tokens go. The levers are on Context & cost and Models & cost — give the cheap roles a cheap model, use compaction, and keep long-lived instructions short. Each subagent and each advisor call is a separate conversation, and costs like one.

Nothing checks the work at the end

The independent check by a second agent is off by default. It is a setting you switch on when you want it. What runs on its own is only what you ask for: /goal judges each time the agent thinks it is done whether your condition holds, and sends it back to work if not (up to 40 checks by default). If you want a mission to end on “the tests pass”, set a goal.

Scheduled tasks did not run

The server was not running at that time. Closing the interface does not stop it, but monixcode stop and a reboot do. Install it as a login service with monixcode service install. See Scheduled tasks.

The screen looks broken

The interface is laid out to fit a terminal of 80 columns by 24 rows; a smaller window cuts panels off. Make the window bigger, or turn on Compact mode under Settings ▸ Display. If long output looks odd, a terminal with full colour and Unicode support helps.

A command hangs

The agent's shell has no terminal, so a command that asks a question or opens an editor (for example an interactive rebase) waits forever. Press Esc to stop the mission and tell the agent to use the non-interactive form of the command. Commands that run longer than about ten seconds move to the background, and long-running servers belong in a background command.

Still stuck

Write to [email protected] and include the output of monixcode doctor and the last lines of monixcode logs.