Troubleshooting
Start with doctor
runmarq doctorIt reports the collector's state and latency, spooled events, every integration's checks and pending steps, and recent errors, and says what to do next. It exits with status 1 when something needs attention, and runmarq doctor --json gives the same report for scripts or a bug report.
Common problems
An integration says “waiting for first event”.
The configuration is in place but no event has arrived yet. Start a new session in the agent and send a prompt; sessions that were already open may not have loaded the new hooks. For Codex, run /hooks inside Codex and trust the runmarq entries first.
Setup says it is refusing to modify a file.
The agent's configuration file is not valid JSON, or a hooks entry is not a list. runmarq never rewrites a file it cannot parse. Fix or move the file, then run setup again.
The collector is not running.
Hooks keep working: events are written to a small spool on disk and replayed with their original times when the collector starts. Start it with runmarq collector start or by opening the desktop app.
A run shows “Status unknown”.
No events arrived for 20 minutes while the run was working, or runmarq restarted during the run. runmarq does not guess that it finished. The run resumes as soon as the agent sends another event. If Claude Code or Codex was closed, runmarq usually sees its process exit within seconds and marks the run cancelled instead.
A run I interrupted shows as cancelled.
That is intended. An interrupted run did not finish, so it is never counted as finished or used as an ordinary duration.
Estimates are very wide.
With little local history, estimates rely on conservative built-in values. They narrow as your runs are recorded. See How estimates work.
Run activity shows no token counts.
Token counts come from the session files Claude Code and Codex write on your computer; Cursor does not write one runmarq can read. Check that Settings → Estimation signals → “Read token counts from agent transcripts” is on. Counts appear after the agent's first response in a run.
Working-tree changes do not appear.
Changes are measured with git diff against the last commit, so the folder the agent works in must be a git repository with at least one commit, and git must be on your path. A repository too large to compare within three seconds is skipped rather than slowing anything down.
Insights says a model is not in use.
That is expected early on. The phase simulation needs ten finished runs with tool activity, range calibration about 34 finished runs, and the learned model 100. A model that did not improve forecasts on your recent runs is also left out until it does.
A run says it may be stuck.
runmarq saw the same tool fail three times in a row, one tool call run far longer than that command usually takes, or the run go well past its estimate with nothing happening for five minutes. It is a prompt to look, not a verdict: the warning clears by itself when the agent makes progress. Turn the notification off in Settings → Notifications.
The Usage page does not match my plan's meter.
It counts the output tokens your agents wrote into their transcripts on this computer. Input and cached tokens are not included, and runmarq does not know your plan's limits, so treat it as a local tally rather than the vendor's figure.
No notifications appear.
Check Settings → Notifications, including quiet mode and the minimum run length, and your operating system's notification permission for runmarq. Finish and failure notifications are skipped for runs shorter than the minimum.
Where things are
| Data folder | %LOCALAPPDATA%\runmarq, ~/Library/Application Support/runmarq or ~/.local/share/runmarq |
| Logs | logs/ in the data folder: one file per day, seven kept, plus hook.log |
| Configuration backups | backups/ in the data folder, one copy per change |
| Hook executable | bin/runmarq in the data folder |
Set RUNMARQ_LOG=debug before starting the collector for more detail. Logs contain timing and errors, never prompts or file contents. Set RUNMARQ_HOME to use a different data folder.