Skip to content

Verify & Repair Installation

Test your installation and fix common issues.

Quick Health Check

Run the comprehensive health check:

coding --health

System Healthy

A healthy system shows all services in green. If you see red indicators, follow the troubleshooting steps below.

Automated Test Suite

The test script verifies all components:

# Check-only mode (default)
./scripts/test-coding.sh

# Interactive repair mode
./scripts/test-coding.sh --interactive

# Verbose output
./scripts/test-coding.sh --verbose

Test Categories

Test What It Checks
Prerequisites Node.js, Git, jq, Docker versions
Commands coding, vkb, ukb in PATH
Configuration .env, hooks, MCP config
Services Docker containers or native processes
Connectivity Health endpoints, port availability
Knowledge Base Graph database accessibility

Detailed Verification

1. Check Prerequisites

# Node.js 18+
node --version

# Git
git --version

# jq
jq --version

# Docker
docker --version
docker info

2. Verify Commands Available

# Should show help
coding --help
vkb --help

# Check locations
which coding
which vkb

If commands not found, check your PATH:

echo $PATH | grep -q "Agentic/coding/bin" && echo "OK" || echo "Missing from PATH"

3. Check Docker Services

# List running containers
docker compose -f ~/Agentic/coding/docker/docker-compose.yml ps

# Expected output shows these services running:
# - coding-services (main MCP servers)
# - memgraph (graph database)
# - qdrant (vector database)

4. Test Health Endpoints

# Semantic Analysis MCP
curl -s http://localhost:3848/health | jq .

# Constraint Monitor MCP
curl -s http://localhost:3031/health | jq .

# VKB Server
curl -s http://localhost:8080/health | jq .

# Health Dashboard
curl -s http://localhost:3032/health | jq .

5. Verify LSL Monitor

# Check ETM heartbeats via the coordinator (Phase 33+: .health/*.json files
# stopped being written; coordinator's lsl slice is now the source of truth)
curl -fs http://localhost:3034/health/state \
  | jq '.lsl | to_entries | map(select(.key | endswith(":coding"))) | .[0].value | {status, lastBeat, projectName}'

# Check if monitor process is running
ps aux | grep -v grep | grep "enhanced-transcript-monitor"

6. Test Knowledge Base

# Check knowledge store exists
ls -la .data/knowledge-graph/

# Test VKB connection
curl -s http://localhost:8080/api/entities | jq 'length'

Common Issues and Fixes

Services Not Starting

Symptoms: Health check shows services as red/unavailable

Fix: 

# Restart Docker services
docker compose -f docker/docker-compose.yml restart

# If that fails, rebuild
docker compose -f docker/docker-compose.yml down
docker compose -f docker/docker-compose.yml up -d --build

Port Conflicts

Symptoms: "Address already in use" errors

Fix: 

# Find what's using the port
lsof -i :8080

# Kill the process or change port in .env.ports
nano .env.ports

# Restart services after port change
docker compose -f docker/docker-compose.yml down
docker compose -f docker/docker-compose.yml up -d

MCP Connection Errors

Symptoms: Claude can't connect to MCP servers

Fix: 

# Verify MCP config
cat ~/.claude/settings.json | jq '.mcpServers'

# Reinstall hooks and config
./install.sh --mcp-only

LSL Not Recording

Symptoms: No files in .specstory/history/

Fix: 

# Check ETM heartbeat via coordinator (Phase 33+)
curl -fs http://localhost:3034/health/state \
  | jq '.lsl | to_entries | map(select(.key | endswith(":coding")))'

# Restart monitor
coding --restart-monitor

# If still failing, check logs
tail -100 .logs/transcript-monitor-test.log

Knowledge Base Corrupted

Symptoms: VKB shows errors, ukb fails

Fix: 

# Backup current data
cp -r .data/knowledge-graph .data/knowledge-graph.backup

# Reset knowledge base
rm -rf .data/knowledge-graph
mkdir -p .data/knowledge-graph

# Re-run full analysis
# (within Claude session)
ukb full

Repair Commands

Full Repair

./install.sh --repair

This will: 1. Check all prerequisites 2. Reinstall missing components 3. Rebuild Docker containers 4. Reset configuration to defaults 5. Restart all services

Selective Repair

# Repair only MCP configuration
./install.sh --mcp-only

# Repair only hooks
./install.sh --hooks-only

# Rebuild Docker containers
cd docker && docker-compose build --no-cache && docker-compose up -d

Reset to Clean State

Data Loss

This removes all local data including knowledge base and session logs.

# Stop everything
docker compose -f docker/docker-compose.yml down 2>/dev/null
pkill -f "coding"

# Remove state files
rm -rf .data .specstory .health .logs .cache
rm -f .transition-in-progress

# Reinstall
./install.sh

Diagnostic Information

When reporting issues, include this diagnostic output:

# Generate diagnostic report
coding --diagnostics > diagnostics.txt

# Or manually collect:
echo "=== System ===" >> diagnostics.txt
uname -a >> diagnostics.txt
echo "=== Node ===" >> diagnostics.txt
node --version >> diagnostics.txt
echo "=== Docker ===" >> diagnostics.txt
docker --version >> diagnostics.txt
docker compose version >> diagnostics.txt
echo "=== Services ===" >> diagnostics.txt
docker compose -f docker/docker-compose.yml ps 2>&1 >> diagnostics.txt
echo "=== Health ===" >> diagnostics.txt
coding --health 2>&1 >> diagnostics.txt