Skip to content
AASC
Documentation pages

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 (from source)
npm start -- --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 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