kbanc85/claudia/diagnose

Claude Code and agent skill by kbanc85/claudia

Trust tier 2
  • community
LLM review pending
Source check pending

Checking that the SKILL.md file is still in the repository.

Check memory system health and troubleshoot connectivity issues. Use when memory commands aren't working, at session start if something seems wrong, or when user asks about memory status. See also: `memory-health` for the data-quality dashboard once connectivity is confirmed.

Install

npx vskill@latest install kbanc85/claudia/diagnose

SKILL.md

Diagnose

System health check for Claudia's memory infrastructure. Run this when:

  • Memory commands seem unavailable
  • Session context isn't loading
  • User asks "is my memory working?"
  • Something feels off with persistence

Process

Step 1: Check .mcp.json Configuration

Read the project's .mcp.json file and verify:

  • A claudia-memory entry exists under mcpServers
  • The command field points to a real Python binary
  • The args include --project-dir matching the current directory
bash
cat .mcp.json 2>/dev/null || echo "No .mcp.json found"

If .mcp.json is missing or has no claudia-memory entry, the daemon was never configured. Fix:

bash
npx get-claudia .

If the Python binary in the command field doesn't exist:

bash
# Check if venv exists
ls -la ~/.claudia/daemon/venv/bin/python 2>/dev/null || echo "Daemon venv not found"
Step 1b: Check Active MCP Servers

List all active MCP servers (entries without _disabled prefix):

bash
python3 -c "
import json
c = json.load(open('.mcp.json'))
servers = c.get('mcpServers', {})
active = [k for k, v in servers.items() if not k.startswith('_')]
stdio = [k for k in active if servers[k].get('type', 'stdio') == 'stdio']
http = [k for k in active if servers[k].get('type') == 'http']
print(f'Active servers ({len(active)}): {chr(44).join(active)}')
print(f' stdio: {chr(44).join(stdio) or \"none\"}')
print(f' http: {chr(44).join(http) or \"none\"}')
"
Step 2: Run Preflight Check

The daemon has a built-in preflight validator that tests all 11 startup steps:

bash
# Extract the Python path from .mcp.json and run preflight
VENV_PYTHON=$(python3 -c "import json; c=json.load(open('.mcp.json')); print(c.get('mcpServers',{}).get('claudia-memory',{}).get('command',''))" 2>/dev/null)
if [[ -n "$VENV_PYTHON" && -x "$VENV_PYTHON" ]]; then
"$VENV_PYTHON" -m claudia_memory --preflight --project-dir "$PWD"
else
echo "Cannot find daemon Python binary. Re-run: npx get-claudia ."
fi

If the preflight file exists, read it for structured results:

bash
cat ~/.claudia/daemon-preflight.json 2>/dev/null
Step 3: Check Session Manifest

The daemon writes a manifest when it successfully enters the MCP loop:

bash
cat ~/.claudia/daemon-session.json 2>/dev/null || echo "No session manifest (daemon never started)"

If the manifest exists, check whether the process is still alive:

bash
PID=$(python3 -c "import json; print(json.load(open('$HOME/.claudia/daemon-session.json')).get('pid',''))" 2>/dev/null)
if [[ -n "$PID" ]]; then
ps -p "$PID" > /dev/null 2>&1 && echo "Daemon running (PID $PID)" || echo "Daemon died (PID $PID no longer running)"
fi
Step 4: Check Standalone Daemon
bash
curl -s http://localhost:3848/status 2>/dev/null || echo "Standalone daemon not running (this is normal if using MCP-only mode)"
Step 5: Check Database Directly
bash
ls -la ~/.claudia/memory/*.db 2>/dev/null || echo "No database files found"
# If database exists, check record counts
for db_file in ~/.claudia/memory/*.db; do
[[ -f "$db_file" ]] || continue
echo "Database: $db_file"
sqlite3 "$db_file" "SELECT 'memories: ' || COUNT(*) FROM memories; SELECT 'entities: ' || COUNT(*) FROM entities;" 2>/dev/null || echo " Cannot query (may be locked)"
done
Step 6: Check Embedding Model
bash
ollama list 2>/dev/null | grep -E "minilm|nomic|mxbai" || echo "No embedding model found (memory works without it, but vector search is disabled)"
Step 7: Report Results

Format the diagnosis as:

---
**Memory System Diagnosis**
| Component | Status | Details |
|-----------|--------|---------|
| .mcp.json config | ✅/❌ | [daemon entry present/missing] |
| Active MCP servers | ✅/⚠️ | [list of active servers] |
| Daemon Python binary | ✅/❌ | [path exists/missing] |
| Preflight | ✅/❌ | [all passed / N failures] |
| Session manifest | ✅/❌ | [running/died/never started] |
| Standalone daemon | ✅/❌/➖ | [healthy/not running] |
| Database | ✅/❌ | [path, record counts] |
| Embedding model | ✅/❌ | [model name or "not found"] |
**Overall:** [Healthy / Degraded / Not Connected]
[If issues found, show the specific fix from preflight results]
---

Common Issues and Fixes

Issue: "MCP server failed" in Codex

Most likely cause: The daemon crashes during startup before reaching the MCP handshake.

Fix: Run the preflight check to see exactly which step fails:

bash
~/.claudia/daemon/venv/bin/python -m claudia_memory --preflight --project-dir "$PWD"

If preflight shows fixable issues, try auto-repair:

bash
~/.claudia/daemon/venv/bin/python -m claudia_memory --repair --project-dir "$PWD"
Issue: Tools not in palette but no error

Cause: Daemon started but exited before Codex could handshake, or Codex closed stdin too early.

Fix: Check the session manifest:

bash
cat ~/.claudia/daemon-session.json
  • If missing: daemon never reached the MCP loop (run preflight)
  • If present with exited_at: daemon started and exited cleanly (check stdin_type, should be "pipe")
  • If present without exited_at and PID is dead: daemon crashed after starting
Issue: Preflight shows db_connect FAIL

Cause: Database is locked by another process.

Fix:

bash
# Find processes using the database
lsof ~/.claudia/memory/*.db 2>/dev/null
# Or try auto-repair
~/.claudia/daemon/venv/bin/python -m claudia_memory --repair --project-dir "$PWD"
Issue: Preflight shows schema_load FAIL

Cause: The claudia-memory package is corrupted or incompletely installed.

Fix:

bash
~/.claudia/daemon/venv/bin/pip install --force-reinstall claudia-memory

Or re-run the installer:

bash
npx get-claudia .
Issue: Preflight shows sqlite_vec WARN

Cause: sqlite-vec extension not installed. Memory works without it, but vector search is disabled.

Fix:

bash
~/.claudia/daemon/venv/bin/pip install sqlite-vec
Issue: Daemon venv not found

Cause: Fresh install or venv was deleted.

Fix:

bash
npx get-claudia .

This recreates the venv and installs the daemon.

Issue: Wrong project directory

Cause: .mcp.json has a different --project-dir than expected.

Fix: Check the args in .mcp.json:

bash
python3 -c "import json; c=json.load(open('.mcp.json')); print(c['mcpServers']['claudia-memory']['args'])"

The --project-dir should match your current working directory. Re-run npx get-claudia . from the correct directory to fix it.

Issue: Python 3.10+ not found

Cause: System Python is too old for the daemon.

Fix: Install Python 3.10+ from python.org, Homebrew (brew install python@3.12), or your package manager.

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewNot runA model review is scheduled for the next rescan.

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

Source

Popularity

Repository stars
292
Repository forks
43
Repository npm downloads, 7 days
1,433
7-day trend score
46

Stars and forks are for the whole GitHub repository, not this skill alone. Downloads are for the repository's npm package. Refreshed 22 Mar 2026, 7 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/kbanc85/claudia/diagnose/badge)](https://verified-skill.com/skills/kbanc85/claudia/diagnose)

Something wrong with this skill or its page? Tell us.