Skip to main content
Guide · How-to

Troubleshooting

Common fixes: hook not registering, MCP not activating, grammar staleness, index rebuild.

Start here

senkani doctor --fix

Checks every expected file, every registration entry, every grammar version. --fix attempts repair for each amber/red finding.

Hook not registering

Symptom: tool calls go through but no compression happens, or the Agent Timeline pane stays empty.

  1. Confirm ~/.claude/settings.json has PreToolUse + PostToolUse entries pointing at ~/.senkani/bin/senkani-hook.
  2. Confirm the hook binary exists and is executable: ls -l ~/.senkani/bin/senkani-hook.
  3. Re-run senkani init — it's idempotent.

MCP server not activating

Symptom: agent doesn't see any senkani_* tools.

  1. Confirm SENKANI_PANE_ID is set in the shell: echo $SENKANI_PANE_ID. If empty, you're in a non-Senkani terminal — launch claude inside a Terminal pane the app opened.
  2. Confirm the MCP server entry in ~/.claude/settings.json.
  3. Run senkani_version (tool) or senkani doctor.

Grammar staleness warning

Symptom: senkani doctor reports SKIP with "grammar X is N days stale."

This is a non-blocking advisory — it never fails CI. Stale = upstream has a newer version AND vendored > 30 days. Within the window, outdated grammars roll up as PASS. Over the window, SKIP (not FAIL). If you want to update, the repo's swift package update pulls the latest grammars.

Index out of sync

Symptom: senkani search returns stale results or can't find a symbol you just added.

senkani index --force

Forces a full rebuild. Normally the index updates incrementally via FSEvents — but after switching branches or restoring from a backup, the cursor can get out of sync.

Budget cap triggered unexpectedly

Symptom: tool calls denied with "budget exceeded."

senkani stats

Shows spend against the caps. If you want to raise them: edit ~/.senkani/config.json or set SENKANI_BUDGET_DAILY/SENKANI_BUDGET_WEEKLY.

Still stuck?

Open an issue at github.com/ckluis/senkani/issues. Include the output of senkani doctor (with any paths redacted) and the relevant slice of senkani stats --security.