Skip to content
AASC
中文
Documentation pages

Troubleshooting

Common issues and solutions for the AI Agent Session Center.

macOS Says the App Is Damaged

The desktop app is not notarized by Apple yet, so macOS says it is "damaged and can't be opened". It is not damaged. Click Cancel, not Move to Trash. Then clear the download flag in Terminal:

xattr -cr "/Applications/AI Agent Session Center.app"

Open the app again. You need to do this after installing each new version.

Port 3333 in Use

When the port is taken, the server force-kills the process that holds it and retries. To use a different port instead:

# CLI flag (from source)
npm start -- --port 4444

# Environment variable
PORT=4444 npm start

Or set port in server-config.json:

{
  "port": 4444
}

Edit the file. Do not overwrite it with a new one, because it also holds your password and other settings.

Native Module Errors

If you run from source and see "compiled against a different Node.js version", rebuild the native modules:

npm rebuild better-sqlite3 node-pty

Hooks Not Firing

Step 1: Verify hooks are registered

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

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: Check that events reach the queue

Leave this running, then send a prompt in a Claude Code session:

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

A line should appear for each event. If none does, the hook is not running. If lines appear but no card does, see "Sessions Not Appearing" below.

Step 5: Re-install hooks

npm run install-hooks

The server also registers hooks again every time it starts.

jq Not Installed

The hook script uses jq to add the process, terminal and environment details that session matching needs. 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

The server creates it when it starts.

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

Step 5: Check how the agent was started

  • A process with no terminal, such as claude -p or a CI run, never makes a card.
  • An agent that was already running when you installed the hooks has sent no events yet. On macOS and Linux, AASC finds running interactive claude processes every 20 seconds and shows them as external cards.
  • Two sessions in one folder can occasionally cross-link, because matching is a best guess.

A Phone or Another Device Cannot Connect

  • A password is required. Without one, every device except your own computer is refused (HTTP 403, or WebSocket close code 4003). Run npm run set-password.
  • Sessions are hidden until you share them. A connected device can see an empty list. Use the Share button on a session, or turn on Share new sessions with my devices in the devices menu.
  • Check the address and port. Use http://your-address:3333, with your own port if you changed it. The connection is plain HTTP.
  • A paired phone and the password. Changing the dashboard password revokes every paired phone. Pair them again.

No Pair a phone or computer in the devices menu? It is there by default from 2.10.60. On an older version, or when phonePairing is false or AASC_PHONE_PAIRING=0 is set, turn it on and restart AASC. See Configuration.

WebSocket Disconnections

The dashboard reconnects on its own, with a growing delay:

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

After a reconnect, the dashboard asks the server for the events it missed. The server keeps the last 500 events. If sessions look stale, refresh the browser.

Terminal Not Connecting

Local terminals:

  • Make sure $SHELL is set to a real shell.
  • Check that node-pty is installed: npm ls node-pty. If it fails to load, run npm rebuild better-sqlite3 node-pty.
  • If AASC says the session or terminal limit is reached, kill a session you no longer need. The limits are 50 sessions and 130 terminals.

SSH terminals (the New Session form starts local terminals, so this applies to SSH sessions restored from a saved workspace):

  • 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

3D Scene Performance

The 3D Cyberdrome scene is off by default. If it is slow:

  • Turn it off: use the 3D On and 3D Off button on the LIVE page.
  • Reduce sessions: remove ended sessions to reduce the robot count.
  • Lower animation intensity: Settings, then APPEARANCE, then Intensity.
  • Check your GPU: the scene uses WebGL, so make sure hardware acceleration is on in your browser.

Central Sessions

  • The Central session picker is missing. Central sessions are off by default from 2.10.60: turn on Central sessions (MCP) in Settings, ADVANCED, and restart AASC. The picker shows only on your own computer's dashboard, and it does not exist in the phone app.
  • A scope is greyed out. That scope already has a central. A project or room has one central at most.
  • A central's call is refused. The session may be on Hands off, or you may have typed in it in the last 60 seconds, or stopped it with Esc. See Central Sessions.
  • A central waits and nothing happens. It may be waiting for a confirm card. Open the dashboard window on your computer. The card is in the bottom-right corner. A card expires after 5 minutes.

Full Reset

To reset a source install:

npm run reset

This will:

  1. Back up the current state into data/backups/.
  2. Remove all dashboard hooks from ~/.claude/settings.json and ~/.codex/config.toml, and the hook scripts.
  3. Delete data/server-config.json and data/sessions.db, and the queue folder in /tmp.
  4. Tell open browsers to clear their local data.

It works on the data/ folder of the repository, not on the desktop app's own folder. To set up again from source, run npm run setup.

Getting Help

  • Version info: Settings, ADVANCED opens on About, with the AASC version, its build date and commit. Copy version info copies them for an issue. On the phone, More, This phone shows the app's version.
  • GitHub Issues: github.com/coding-by-feng/ai-agent-session-center/issues
  • Debug mode: npm run debug for verbose logging
  • Log file: data/logs/server.log from source. The desktop app writes logs/server.log in its own folder. The log rotates at 5 MB.
  • Hook stats: GET /api/hook-stats shows delivery latency and processing metrics
  • MQ stats: GET /api/mq-stats shows message queue health