AASC

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 via the setup wizard or settings panel:

npx ai-agent-session-center --setup

Or update data/server-config.json:

{
  "hookDensity": "high"
}

Multi-CLI Support#

The dashboard can monitor three AI coding CLIs simultaneously:

| CLI | Events | Notes | |-----|--------|-------| | Claude Code | 14 events | Full lifecycle, approval detection, teams | | Gemini CLI | 7 events | BeforeAgent, BeforeTool, AfterTool, AfterAgent, etc. | | Codex | 1 event | agent-turn-complete |

Enable multiple CLIs during setup or by editing the config:

{
  "enabledClis": ["claude", "gemini", "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
npx ai-agent-session-center --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)
Previous← Getting StartedNextSession Management →