Troubleshooting¶

Common issues and solutions.

Quick Diagnostics¶

# System health check
./scripts/test-coding.sh

# LSL validation
node scripts/validate-lsl-config.js

# Docker services status
docker compose -f docker/docker-compose.yml ps

Installation Issues¶

Commands Not Found¶

# Reload shell configuration
source ~/.bashrc  # or ~/.zshrc

# Verify PATH
echo $PATH | grep coding

# If missing, reinstall
./install.sh --update-shell-config

Permission Errors¶

# Make scripts executable
chmod +x install.sh
chmod +x bin/*

# Run installer
./install.sh

MCP Servers Not Loading¶

# Check MCP configuration
cat ~/.config/Claude/claude_desktop_config.json

# Reinstall MCP config
./install.sh --update-mcp-config

# Check server logs
ls ~/.claude/logs/mcp*.log

Agent Drops Back to the Shell on Startup¶

If coding prints [tmux-wrapper] Creating tmux session: … and then returns straight to the shell prompt (no interactive agent), the agent process exited during startup before the session became interactive — usually a transient timing race (e.g. an MCP pre-flight gate such as VKB on port 8080 not yet ready). The wrapper now surfaces why instead of failing silently: it prints a ⚠️ Session … exited diagnostic with the tail of the captured launch output, and writes the full log to .logs/launch/<session>.log.

# Inspect the most recent failed launch
ls -t .logs/launch/*.log | head -1 | xargs tail -40

# Re-running usually clears a startup timing race
coding --claude

LSL Issues¶

LSL Files Not Generated¶

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

# Check ETM heartbeat via coordinator (Phase 33+: .health/*.json files are
# no longer written; coordinator's lsl slice is the source of truth)
curl -fs http://localhost:3034/health/state \
  | jq '.lsl | to_entries | map(select(.key | endswith(":coding")))'

# Restart monitor
coding --restart-monitor

Classification Not Working¶

# Check classification logs
ls -la .specstory/logs/classification/

# Verify configuration
cat config/live-logging-config.json | jq '.embedding_classifier'

Recovery from Transcripts¶

# Batch recover LSL files
PROJECT_PATH=/path/to/project CODING_REPO=/path/to/coding \
  node scripts/batch-lsl-processor.js from-transcripts ~/.claude/projects/-path-to-project

# Recover specific date range
PROJECT_PATH=/path/to/project CODING_REPO=/path/to/coding \
  node scripts/batch-lsl-processor.js retroactive 2024-12-01 2024-12-03

Docker Issues¶

Container Won't Start¶

# First try: clean start (kills orphaned processes hogging ports)
coding --force

# Check logs if --force doesn't help
docker compose -f docker/docker-compose.yml logs coding-services

# Force rebuild
docker compose -f docker/docker-compose.yml build --no-cache
docker compose -f docker/docker-compose.yml up -d

Port Conflicts¶

# Recommended: force-clean all coding processes and restart
coding --force

# This kills supervisors, health monitors, all processes on coding ports,
# stops Docker containers, then proceeds with a clean startup.
# Combine with agent flags: coding --force --claude

# Manual investigation if --force doesn't resolve it
lsof -i :3848
kill $(lsof -ti :3848)

# Or change ports in .env.ports

Connection Refused¶

# Check container status
docker compose -f docker/docker-compose.yml ps

# Test health endpoint
curl -v http://localhost:3848/health

Volume Permission Issues¶

# Fix directory permissions
mkdir -p .data/knowledge-graph .specstory/history
chmod -R 755 .data/ .specstory/

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

Knowledge Base Issues¶

VKB Won't Start¶

# Check if installed
ls -la integrations/memory-visualizer/

# If missing, initialize submodule
git submodule update --init --recursive integrations/memory-visualizer
cd integrations/memory-visualizer
npm install && npm run build

# Test viewer
vkb --debug

Missing Knowledge Export¶

# Check knowledge-export files
ls -la .data/knowledge-export/*.json

# If missing, graph database will create on next run

Constraint Monitor Issues¶

Dashboard Not Loading¶

# Check if services are running
lsof -i :3030
lsof -i :3031

# Start dashboard
cd integrations/mcp-constraint-monitor
PORT=3030 npm run dashboard

Hooks Not Firing¶

# Check hook configuration
cat ~/.claude/settings.json | jq '.hooks'

# Verify hook script exists
ls -la integrations/mcp-constraint-monitor/src/hooks/pre-tool-hook-wrapper.js

Performance Issues¶

High Memory Usage¶

# Increase Node.js memory
export NODE_OPTIONS="--max_old_space_size=4096"

# Restart with higher limit
NODE_OPTIONS="--max_old_space_size=4096" coding --claude

Slow Processing¶

# Process with lower priority
nice -n 19 node scripts/enhanced-transcript-monitor.js &

# Reduce monitoring frequency in config

Complete Reset¶

If installation is corrupted:

# Uninstall
./uninstall.sh

# Remove all data (WARNING: loses knowledge base)
rm -rf ~/.coding-tools/
rm -rf integrations/memory-visualizer/node_modules
rm -rf .data/knowledge-export/*.json

# Reinstall
./install.sh
source ~/.bashrc

Getting Help¶

Diagnostic Information¶

# Collect diagnostics
echo "=== System Info ===" > diagnostics.txt
uname -a >> diagnostics.txt
node --version >> diagnostics.txt
echo "PWD: $(pwd)" >> diagnostics.txt

echo -e "\n=== Environment ===" >> diagnostics.txt
env | grep -E "(USER|CODING|LSL)" >> diagnostics.txt

echo -e "\n=== Configuration ===" >> diagnostics.txt
cat .specstory/lsl-config.json 2>/dev/null >> diagnostics.txt

echo "Diagnostics collected in diagnostics.txt"

Support Resources¶

GitHub Issues
Documentation
Configuration Validator: node scripts/validate-lsl-config.js