Troubleshooting

Start here

eklavya doctor

Use npx eklavya doctor if you did not install the global command. Doctor checks the runtime, database driver, plugin registration, configuration and optional dependencies. Follow the repair it reports, then restart Claude Code.

Eklavya’s hooks allow your session to continue when they fail, so silence alone does not prove it is healthy. eklavya install repairs a broken installation without resetting your learning history or settings.

Installation and updates

Symptom	Check or repair
Banner lacks the Learning line, the memory health line or recalled memory	Session start gives these details about seven seconds in total and drops any that are not ready, so a very large database shows a thinner banner instead of none. Run eklavya memory status and eklavya doctor to see what is slow; EKLAVYA_SESSION_START_BUDGET_MS changes the budget (the host ends the hook at 10 seconds).
No session banner	Check quiet with eklavya config get, then inspect /plugin and eklavya doctor. A marketplace install may still need npx eklavya install to finish the runtime. Claude Code stops a hook that runs past its 10-second limit and shows nothing, so a banner missing in only one large project can mean session start was too slow there. Update Eklavya (eklavya update); an older memory-health check took about 10 seconds on a project with many memory entries.
Plugin registered but not enabled	Enable Eklavya through /plugin, or rerun eklavya install.
Database missing or session says it cannot open the database	Read doctor’s database and driver rows. Confirm Node.js 22+, then run eklavya install if the driver is missing or incompatible.
It stopped working after upgrading Node.js	The native SQLite driver may need rebuilding for the new Node version. eklavya install repairs it.
Installer reports invalid JSON	Fix the named file before retrying. Eklavya refuses to overwrite invalid configuration. Backups can restore a previous version.
Skill path contains a different skill named eklavya	Eklavya preserves your existing skill. Move or rename it yourself, then reinstall.
Runtime and plugin versions differ	Run eklavya update and restart. Automatic updates normally catch up in a later session; check auto_update if they do not. A newer runtime is never downgraded.
Automatic update failed	Run eklavya update for the full error; inspect ~/.eklavya/update.log. Missing npm usually means Claude’s launch environment has a different PATH; a permissions error needs the named files’ ownership repaired.
Dashboard link missing or not loading	Run eklavya dashboard status. If another program holds port 41729, the greeting shows eklavya dashboard instead of a link; stop that program, or keep using eklavya dashboard, which falls back to another port. If the dashboard keeps failing to start, read ~/.eklavya/dashboard.log. If the version at the foot of its sidebar is older than eklavya --version, run eklavya dashboard stop then eklavya dashboard.
Another installation is running	Let the process named by the installer finish, then retry. Do not delete its lock while it is active.

Updates and removal explains automatic checks, backups and runtime catch-up.

Questions and settings

Symptom	Check or repair
No questions	Check quiz.enabled. Automatic questions also wait until the session changes code (quiz.only_on_changes), so read-only sessions get none, and a session started outside any git repository waits for an edit inside one (files under artifacts/ or reports/ do not count, nor does a git pull), and they cover only work logged since you last came back after more than an hour away. Run /eklavya:quiz to be asked anyway. Claude must log concepts tied to the work before Eklavya can ask about them.
The quiz panel does not show	It is experimental. Check eklavya config get quiz.panel is true, you are on the Claude Code terminal CLI or the Desktop Code tab (other surfaces keep the question card; if Desktop cannot show the panel it uses the card too), and the plugin is current. The planner uses the panel only while it has reported in during the last 90 seconds and its last report did not say the host could not show it. A session opened without a project folder (Desktop’s “Add folder” bar) is treated as having no project; if the panel still does not open there, open a project folder. In a terminal narrower than 144 columns the panel waits: run /eklavya-panel. If a question was waiting and you closed the panel, /eklavya-panel reopens it. To go back to the card, run eklavya config set quiz.panel false.
Questions stopped partway through	The session may have reached its budget, have no eligible concepts, or still be within the checkpoint interval. Ask Claude to log the current task’s concepts, then try /eklavya:quiz.
Questions only arrive at task completion	Check cadence. eklavya config set cadence as-you-go enables mid-task checkpoints; Claude also needs to log concepts while working.
denied by auto mode on any Eklavya tool (panel_sync, get_session_quiz_plan, record_attempt and others), or no question after a turn	Claude Code’s auto mode refused a call Eklavya makes on its own, sometimes with an unrelated reason such as “Irreversible Local Destruction”. Allow the ten tools in ~/.claude/settings.json, or ask Claude to; see if auto mode blocks Eklavya.
eklavya:eklavya-explainer denied by auto mode	Usually harmless. Auto mode judges every agent the panel starts, most often refusing because its classifier was briefly unavailable. The panel asks once more, then hands the explainer to Claude, whose own start normally gets the page written. No allow rule changes this: auto mode drops Agent allow rules.
A question is waiting in the panel and nothing else is asked	By design: one question is open at a time. Answer or skip it, or wait 24 hours for it to expire; an unanswered question is not recorded as a decline.
Too many interruptions	Increase min_minutes_between_checkpoints, decrease max_questions_per_task, or choose cadence: end. See The dials.
Questions are too easy	Run /eklavya:level to see this project’s progress. Difficulty starts easy in a new project; you can also pin a level through the dials.
A global setting seems ignored	eklavya config get shows effective settings and the project’s override file. Change the override with --project.
Questions stopped but memory continues	Expected: quiz.enabled and memory.enabled are separate. eklavya memory status shows whether recording is active.
A repository’s .eklavya.json disappeared	It was migrated into your personal project settings. eklavya config get shows the new path.

A long session has never logged any concepts

After about 12 minutes with no logged concepts, Eklavya reminds Claude to log what the task exercises. It repeats at most every 25 minutes, up to three times. Resuming or compacting resets the reminder state. quiz.enabled: false disables the reminder; quiet does not.

This reminder does not fire after a session has already logged concepts. For that case, ask Claude to log the current task or run /eklavya:quiz.

With memory on, a session that never logs still gets concepts from its own observations at the end of a turn (how). When an observer model summarises in the background, that can take one more turn; if the session changed code, the end of the turn asks Claude to log its concepts and then ask you a question.

Memory and search

Start with:

eklavya memory status

What you see	Next step
capture: off	Review your memory settings. If you kept Claude Mem during installation, Eklavya intentionally does not record.
health: says warn or stalled	Read the reasons printed under it. Each names its own repair: Memory stalled · nothing new remembered for 30h means evidence is arriving and nothing is being summarised, so run eklavya doctor for the cause. See the memory health verdict for every check and threshold.
Pending evidence but no entries	Run eklavya memory process to summarize pending work.
queue: shows paused jobs, or the banner says Memory paused	The paused: line names the cause: resolve provider login, quota or missing executable. The queue checks at most every 30 minutes and resumes by itself once the login is back or an hour after a usage limit; run eklavya memory process to resume now. Until then, recall uses local stand-in observations.
Banner says Memory behind	Jobs have waited more than six hours. Run eklavya doctor; it names a stopped worker or failing provider.
spool drops: above zero	Evidence did not reach the database. eklavya memory replay can recover available evidence from this checkout’s Claude Code transcripts. It also backfills work from before installation.
History is missing after you moved or renamed the folder	Session start re-files it by itself when exactly one missing folder shares this repository’s first commit, and says Memory · moved from …. If the banner says the history is under several moved folders, or the folder moved before this release, run eklavya memory move to list them, then eklavya memory move <old path> from the new checkout.
Search misses another project’s work	Add --all-projects to the search. Searches otherwise use the current checkout.
Imported entries are unplaced	Rerun the import from the source database; use --map-here for a project name that cannot be resolved. See Moving from Claude Mem.
Searches miss Japanese or Chinese text	Prefer retrieval.mode: hybrid; keyword search struggles with unspaced scripts. Try a filename or identifier as the query.
Savings say “unavailable” or show overhead	No emitted reuse means unavailable: a recall that was only prepared is never counted. On small histories, recalled observations can cost more tokens than the original evidence. This is reported rather than hidden.
sync pull says Still owed or Could not read a record	The shared folder has not finished delivering, or is still writing, another device’s records. Records after them were already applied. Run eklavya memory sync pull again once the folder catches up; eklavya memory sync status shows the count still owed beside each peer.
Unwanted content was recorded	Ask Claude to delete the affected memory entry with memory_delete, then adjust privacy.exclude_paths, privacy.exclude_tools or privacy.redact_patterns to prevent recurrence.

To switch from Claude Mem, run eklavya install --memory eklavya after reviewing the migration steps.

Recovery from the version 1.24.0 memory-worker loop

If configuring a memory model created many claude or node processes:

1. Run eklavya config set providers.observer null, then eklavya memory stop.
2. Run eklavya update. On a version without that command, use npm install -g eklavya@latest && eklavya install.
3. Check eklavya memory status: there should be at most one worker PID. Old untracked workers may need to be stopped manually or by restarting.
4. Inspect eklavya memory backlog. It lists helper sessions whether or not they were already summarised. Run eklavya memory backlog discard --helpers to delete them: their batches, their evidence and the memories they produced. Your own sessions are not touched. To keep the unfinished ones instead, use quarantine --helpers; it sets them aside without processing them.

Claude’s first Read of a large file was refused once

When a file of 32 KB or more has history in this project’s memory, Eklavya holds a whole-file Read of a code file and shows the entry titles, the memory_get call and the way to read less: code_outline, then a Read with offset and limit. A repeated whole-file read of that file is held again; a ranged read always goes through. Markdown, YAML, JSON and other files with no outline are never held. To stop the hold, run eklavya config set memory.file_hold false (user or project scope).

Commit gate

Symptom	Check or repair
Commit blocked	/eklavya:gate shows outstanding concepts. /eklavya:quiz starts the required practice; a passing result clears the gate.
You did not expect enforcement	Check the effective quiz.enforced value. To disable a project’s override, run eklavya config set quiz.enforced false --project.
Enforcement enabled but commits pass	Questions must also be enabled. Doctor reports quiz.enabled: false with enforcement. For terminal commits, verify the git hook plus jq and sqlite3. If only commits from a linked worktree pass, update Eklavya: older hooks missed a gate saved under the main checkout.
Git hook never runs	If core.hooksPath points to husky or another manager, add the line printed by Eklavya’s hook installer to that manager’s pre-commit hook.
Claude’s commit escaped enforcement	Shell aliases, command variables and scripts can bypass the Claude-side check. The git hook covers commits at git itself.
Every commit says the gate script is missing	Reinstall Eklavya, or remove its git hook using the command printed by uninstall.

Claude Desktop and Cowork

Symptom	Check or repair
Questions have no Eklavya header chip	Desktop uses cards. Eklavya questions start with [Eklavya] instead; if Claude leaves it off, a hook refuses the question once and Claude asks it again with the line.
/eklavya-panel says “Unknown skill” in Cowork	The panel is a Claude Code mod, so Cowork has neither it nor the command. Cowork also keeps its own plugin list: install Eklavya there (see Installation options) and its questions use the card.
Terminal works but Cowork does not	Cowork needs its own plugin installation. Doctor verifies the Claude Code install only.
Cowork asks about code when you are producing documents	Report your Claude Desktop version; Eklavya may not recognize its session entrypoint. Setting a variable in your terminal does not change Desktop’s hook environment.
Cowork does not block commits	Expected: Cowork does not commit. Enforcement can still ask questions.
Nothing works in a managed Cowork installation	Ask the administrator whether local MCP servers are disabled (isLocalDevMcpEnabled: false) or a full-VM sandbox prevents access to the local runtime.

If a repair fails, open an issue with the Eklavya version, environment and relevant diagnostic output. Remove secrets and private project details first.