Skip to content
AASC
Documentation pages

Configuration

Configure hooks, density levels, multi-CLI support, and server settings.

Hook Density Levels

Hook density controls how many events are captured from your AI CLI sessions.

| Level | Claude Events | Description | |-------|--------------|-------------| | high | All 14 | Full monitoring, best approval detection | | medium | 12 (no TeammateIdle, PreCompact) | Default — good balance of coverage and overhead | | low | 5 (Start, Prompt, Permission, Stop, End) | Minimal overhead, basic session tracking |

Change density in the dashboard's settings panel, or, when you run from source, with the setup wizard:

npm run setup

Or update data/server-config.json:

{
  "hookDensity": "high"
}

Multi-CLI Support

The dashboard can monitor two AI coding CLIs at the same time:

| CLI | Events | Notes | |-----|--------|-------| | Claude Code | 14 events | Full lifecycle, approval detection, teams | | Codex | 5 events (3 at low density) | SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PermissionRequest; turn end through notify |

Enable multiple CLIs during setup or by editing the config:

{
  "enabledClis": ["claude", "codex"]
}

Server Configuration

All server settings live in data/server-config.json:

| Field | Type | Default | Description | |-------|------|---------|-------------| | port | number | 3333 | HTTP/WS listen port | | hookDensity | string | "medium" | high, medium, or low | | debug | boolean | false | Verbose logging | | processCheckInterval | number | 15000 | PID liveness check interval (ms) | | sessionHistoryHours | number | 24 | History retention | | enabledClis | string[] | ["claude"] | Which CLIs to hook | | passwordHash | string | null | Dashboard password (salt:hash) |

Port Configuration

The port is resolved in priority order:

  1. --port CLI flag
  2. PORT environment variable
  3. config.port in data/server-config.json
  4. Default: 3333
# CLI flag (from source)
npm start -- --port 8080

# Environment variable
PORT=8080 npm start

If the port is already in use, the server automatically kills the occupying process and retries.

Hook Management

# Install hooks (respects current density setting)
npm run install-hooks

# Uninstall all dashboard hooks
npm run uninstall-hooks

# Full reset (remove hooks, clean config, create backup)
npm run reset

The hook installer uses atomic writes (write to temp file, then rename) to prevent corrupting your CLI settings files.

Authentication

Optional password protection can be enabled during setup or by running the wizard again. Passwords are hashed with scrypt (timing-safe comparison). Tokens are valid for 24 hours.

When enabled:

  • All API endpoints require authentication
  • WebSocket connections must include a token
  • Hook ingestion (POST /api/hooks) is always unauthenticated (hooks must work without login)