Troubleshooting

Start with eklavya doctor. It answers most of these in one screen, and it checks the install itself — the runtime, the SQLite driver, the plugin’s registration and the chat skill — before anything else. If one of those has broken, doctor says which and tells you to run eklavya install, which is idempotent and repairs all four without touching your history.

That first block matters more than it looks. Eklavya never breaks a session: every hook exits successfully whatever happens. So a broken install and a quiet one look identical from the inside — it just stops asking. doctor is the only thing that tells them apart.

Symptom	Likely cause and fix
No profile line at session start	Either quiet is true, mode is off, the runtime is not installed yet, or the plugin did not load. Run /plugin and check for errors, then eklavya doctor. If you installed through the marketplace, npx eklavya install finishes the runtime immediately.
No questions at all, ever	Check the mode is not off. Then check that Claude is actually logging concepts — with nothing logged there is nothing grounded to ask about. /eklavya:quiz will tell you which of the two it is.
Nothing at all in a long session, and nothing was ever logged	The instruction to log concepts is injected once, at session start, so in a long session it can end up buried under everything that came after it. Eklavya notices this particular case: after about twelve minutes of a session that has logged nothing, it restates the instruction in one line — at most once every twenty-five minutes, and at most three times before it gives up, because a session that logs nothing is also what an unreachable server looks like. Resuming a session or compacting one starts that count again, since the original instruction is reprinted then too. mode: off is what switches the reminder off; quiet does not, because the reminder is context for Claude rather than output for you.
Questions arrived earlier in the session, then stopped	This is the other case, and no reminder fires for it — concepts are logged per task, and a task can legitimately run a long time, so Eklavya cannot tell a quiet stretch from a long one. Ask Claude directly to log what the current task touched, or run /eklavya:quiz.
Questions only arrive at the end, or several in a row	Cadence is end. eklavya config set cadence interleaved — that asks at the seam where a concept is logged, and caps a quiz at one question. If they still arrive late on interleaved, Claude is logging concepts at the end of the task rather than as it works; tell it to log as it goes.
Too many interruptions	Raise min_minutes_between_checkpoints, or lower max_questions_per_task. Switching to end is the blunt version.
Questions feel far too easy	You are on easy, which is where every project starts. Run /eklavya:level to see the runway — you may be close to a promotion. Pin a band only if you are sure.
My personal setting stopped applying	A .eklavya.json in this repository is overriding it. The session banner names which settings; eklavya config get prints the file path.
The database file does not exist	The MCP server never started. Check /plugin for errors and confirm node --version is 22 or newer — below that the native database binding has no prebuilt binary and will not install.
A commit is blocked and I do not know why	/eklavya:gate tells you how many concepts are outstanding. /eklavya:quiz clears it.
Commits are blocked but I never chose enforced	The repository sets it. Open .eklavya.json at the repository root; repo settings beat personal ones by design.
The git hook does not fire	It only acts on repositories whose .eklavya.json sets "mode": "enforced", and it deliberately fails open when jq or sqlite3 is missing. Check both.
Eklavya worked, then went silent after a Node upgrade	The SQLite driver’s prebuilt binary is tied to a Node ABI. eklavya doctor reports this as driver: FAILED; eklavya install rebuilds it.
doctor says the plugin is registered but not enabled	Under enabledPlugins in ~/.claude/settings.json, eklavya@eklavya is false or missing entirely. Re-enable it there, with /plugin in Claude Code, or by running eklavya install.
doctor says the skill is a different skill named eklavya	You have your own ~/.claude/skills/eklavya/. Eklavya will not overwrite it — rename or move yours, then run eklavya install.