AASC

Troubleshooting

Common issues and solutions for the AI Agent Session Center.

Port 3333 in Use#

The server automatically kills the process occupying port 3333 on startup. To use a different port:

# CLI flag
npx ai-agent-session-center --port 4444

# Environment variable
PORT=4444 npm start

# Config file
echo '{"port": 4444}' > data/server-config.json

Hooks Not Firing#

Step 1: Verify hooks are registered

cat ~/.claude/settings.json | grep dashboard-hook

You should see entries with "command": "~/.claude/hooks/dashboard-hook.sh".

Step 2: Verify the hook script exists

ls -la ~/.claude/hooks/dashboard-hook.sh

Step 3: Verify it's executable

chmod +x ~/.claude/hooks/dashboard-hook.sh

Step 4: Test manually

echo '{"session_id":"test","hook_event_name":"SessionStart"}' | ~/.claude/hooks/dashboard-hook.sh

Step 5: Re-install hooks

npm run install-hooks

jq Not Installed#

The hook script requires jq for JSON enrichment. Without it, hooks still work but send unenriched JSON (no PID, TTY, or terminal detection).

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# Verify
jq --version

Sessions Not Appearing#

Step 1: Check the message queue file exists

ls /tmp/claude-session-center/queue.jsonl

Step 2: Check for data

tail -5 /tmp/claude-session-center/queue.jsonl

Step 3: Run in debug mode

npm run debug

Debug mode shows verbose logging for every hook event, session match attempt, and state transition.

Step 4: Verify density includes SessionStart

All density levels include SessionStart. If you changed density, re-install hooks:

npm run install-hooks

WebSocket Disconnections#

The WebSocket client auto-reconnects with exponential backoff:

  • Base delay: 1 second
  • Max delay: 10 seconds
  • Backoff: Doubles each attempt

On reconnect, the client requests missed events from the server's ring buffer (last 500 events). If sessions appear stale, refresh the browser.

Terminal Not Connecting#

SSH connections:

  • Verify your SSH key is accessible: ssh-add -l
  • Test SSH directly: ssh -i ~/.ssh/id_rsa user@host
  • Check the host is in ~/.ssh/config or use the full hostname
  • Verify port 22 is open

Local connections:

  • Ensure $SHELL is set correctly
  • Check that node-pty is installed: npm ls node-pty

3D Scene Performance#

If the 3D Cyberdrome scene is slow:

  • Reduce sessions: Archive ended sessions to reduce robot count
  • Lower animation intensity: Settings > Appearance > Animation Intensity
  • Check GPU: The scene uses WebGL — ensure hardware acceleration is enabled in your browser
  • Close other tabs: WebGL shares GPU resources with other browser tabs

Full Reset#

To completely reset the dashboard:

npm run reset

This will:

  1. Remove all hooks from ~/.claude/settings.json, ~/.gemini/settings.json, and ~/.codex/config.toml
  2. Create a backup of the current config in data/backups/
  3. Remove data/server-config.json
  4. The next startup will re-run the setup wizard

Getting Help#

Previous← API Reference