Claude-Dash Administration Framework

When This Activates

This skill activates for system maintenance:

• Health checks and diagnostics

• Storage cleanup and optimization

• Index management

• Service troubleshooting

System Components

Core Services

Service Purpose Check Command

Watcher File monitoring, index updates ps aux | grep watcher

Gateway MCP routing, caching ps aux | grep gateway

Ollama Local LLM ollama list

Dashboard Visualization Port 3333

Storage Locations

~/.claude-dash/ ├── projects/ # Project memory (indexes, summaries) ├── sessions/ # Session data, transcripts ├── learning/ # Corrections, preferences, calibration ├── mlx-tools/ # Local AI tools (Ollama-based) ├── skills/ # Skill definitions ├── logs/ # Service logs ├── indexes/ # HNSW search indexes └── config.json # Main configuration

Health Checks

Quick Health Check

memory_health action=status

Full Diagnostic

Check services

ps aux | grep -E "(watcher|gateway|ollama)"

Check storage

du -sh ~/.claude-dash/*/

Check recent errors

tail -20 ~/.claude-dash/logs/watcher-error.log

Check gateway metrics

gateway_metrics format=summary

Common Maintenance Tasks

1. Clean Up Storage

Run session archival

python3 ~/.claude-dash/scripts/archive-sessions.py

Run log rotation

~/.claude-dash/scripts/log-rotation.sh

2. Refresh Indexes

Trigger HNSW rebuild

hnsw_status action=rebuild project=gyst

Run freshness check

workers_run worker=freshness project=gyst

3. Consolidate Learning

Run observation consolidation

workers_run worker=consolidate

4. Restart Services

Restart watcher

~/.claude-dash/watcher/start-watcher.sh restart

Restart gateway (via Claude settings or restart Claude)

Troubleshooting

"Memory search returns nothing"

• Check if project is registered in config.json

• Verify index files exist: ls ~/.claude-dash/projects/{project}/

• Check watcher is running

• Trigger reindex if needed

"Hook is slow"

• Check hook timeout in settings

• Review inject-context.sh performance

• Consolidate to single Python process (inject_all_context.py)

"Watcher crashes"

• Check watcher-error.log

• Verify project paths exist

• Check for permission issues

"Ollama not responding"

• Check: ollama list

• Restart: ollama serve

• Verify model exists: ollama pull gemma3:4b-it-qat

Configuration

Main Config (config.json)

{ "projects": [...], "watcher": { "enabled": true, "ignorePatterns": [...], "scanIntervalMs": 5000 } }

Adding a New Project

{ "id": "project-id", "displayName": "Project Name", "path": "/full/path/to/project", "memoryPath": "projects/project-id" }

Performance Metrics

Gateway Efficiency

gateway_metrics format=detailed

Shows:

• Cache hit rate (target: >50%)

• Local routing rate (higher = cheaper)

• Token savings

Learning Status

learning_status component=all

Shows:

• Preferences learned

• Corrections recorded

• Confidence calibration

Scheduled Maintenance

These run automatically via cron:

• 3 AM: Log rotation

• Background: Watcher auto-updates

Manual periodic tasks:

• Weekly: Session archival

• Monthly: Review and clean old projects

• As needed: HNSW index rebuild

Emergency Recovery

Reset Project Memory

rm -rf ~/.claude-dash/projects/{project}/*

Watcher will rebuild on next file change

Reset All Indexes

hnsw_status action=rebuild-all

Clear Corrupted State

Backup first

cp -r ~/.claude-dash ~/.claude-dash.backup

Then clear specific problematic data

rm ~/.claude-dash/sessions/observations.json rm ~/.claude-dash/learning/corrections.json