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 AASC registers with your AI CLI. More events give a more detailed picture. Fewer events cost less.

  • high: all 14 Claude Code events. Full monitoring.
  • medium (default): 13 events. It is every event except TeammateIdle. These are SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, Stop, Notification, SubagentStart, SubagentStop, TaskCompleted, PreCompact and SessionEnd.
  • low: 5 events. These are SessionStart, UserPromptSubmit, PermissionRequest, Stop and SessionEnd. There are no tool events, so AASC cannot see which tools run and its approval timers do not start. PermissionRequest still reports approval dialogs.

Change the density

There are three ways.

  • In the dashboard, open Settings, then the HOOKS tab. Pick a density and install. The hooks change right away.
  • On the command line, from source:
npm run install-hooks -- --density low
  • In server-config.json:
{
  "hookDensity": "high"
}

Every time the server starts, it registers hooks again from hookDensity in server-config.json. That start-up step only adds events that are missing. It does not remove any. If you pick a lower density in Settings, also set it in server-config.json so it stays after a restart.

Multi-CLI Support

AASC can monitor Claude Code and Codex at the same time. Other CLIs are not supported.

  • Claude Code: up to 14 events. It has the full lifecycle, approval detection and teams.
  • Codex: fewer events. At every density you get SessionStart, UserPromptSubmit and PermissionRequest. Medium and high add PreToolUse, PostToolUse, PreCompact and PostCompact. The end of a turn arrives through Codex's notify entry.

Enable both CLIs during setup, or in the config:

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

When AASC starts Codex itself, it adds --no-daemon if your installed Codex supports it. That makes Codex run its hooks from the terminal's own process, so each hook can be matched to its session.

Settings, ADVANCED, Agent CLIs shows the Claude Code and Codex versions on your computer next to the newest ones, and runs each CLI's own update for you. The phone app has the same under More, Settings, Advanced.

Server Configuration

Server settings live in server-config.json.

  • Run from source: data/server-config.json in the repository.
  • Desktop app on macOS: ~/Library/Application Support/ai-agent-session-center/server-config.json.
  • Desktop app on Windows: %APPDATA%\ai-agent-session-center\server-config.json.
  • Desktop app on Linux: ~/.config/ai-agent-session-center/server-config.json.

The server reads the file once when it starts. Restart AASC after you edit it.

  • port (number, default 3333): the HTTP and WebSocket port.
  • hookDensity (string, default "medium"): high, medium or low.
  • debug (boolean, default false): verbose logging.
  • processCheckInterval (number, default 15000): how often AASC checks that session processes are alive, in milliseconds.
  • sessionHistoryHours (number, default 24): the retention choice the setup wizard writes. The server does not read it.
  • enabledClis (string list, default ["claude"]): which CLIs to hook.
  • passwordHash (string, default none): the dashboard password as a salted scrypt hash. Do not edit it by hand. Use npm run set-password.
  • phonePairing (boolean, default on from 2.10.60, off before): whether the devices menu offers Pair a phone or computer. Set it to false to turn pairing off. The environment variable AASC_PHONE_PAIRING=1 (or 0) overrides it.
  • mcp (object): central sessions, off by default from 2.10.60. See Central Sessions.

Port Configuration

The port is resolved in priority order:

  1. --port CLI flag
  2. PORT environment variable
  3. port in 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 force-kills the process that holds it and retries. To run a second copy without that, give it another port with --port.

On macOS and Linux, hooks reach the server through a file queue in /tmp/claude-session-center/, so a different port needs no hook change. The hook script's HTTP fallback always posts to port 3333.

Hook Management

# Install hooks (uses hookDensity from data/server-config.json)
npm run install-hooks

# Remove all dashboard hooks
npm run uninstall-hooks

# Full reset (remove hooks and local data, after a backup)
npm run reset

The hook installer uses atomic writes (write to a temp file, then rename) so it cannot leave your CLI settings half-written.

npm run reset works on the data/ folder of the repository. It backs up first into data/backups/. Then it removes the hooks, the deployed hook scripts, data/server-config.json and data/sessions.db. It also removes the queue folder in /tmp and tells open browsers to clear their local data.

Authentication

On your own computer, the dashboard needs no password. From any other device it needs one.

  • No password set: your computer can use the dashboard. Every other device is refused (HTTP 403, or WebSocket close code 4003).
  • Password set: every API call and WebSocket connection needs a sign-in, from this computer too.

The desktop setup wizard requires a password. To set, check or clear it later:

npm run set-password              # set it (prompted, never typed on the command line)
npm run set-password -- --status  # is one set?
npm run set-password -- --clear   # remove it

A password needs at least 8 characters, with an upper case letter, a lower case letter, a digit and a special character. It is stored as a salted scrypt hash and compared in constant time. After 5 wrong attempts from one address, sign-in is blocked for up to 15 minutes. A sign-in lasts one hour, and the dashboard renews it while it is open.

Hook ingestion (POST /api/hooks) needs no login, but it only accepts requests from your own computer. Hooks must work without signing in.

Changing the password revokes every paired phone, so you must pair them again.

Phone and Other Devices

You can use AASC from another device in two ways.

  • A browser on the same network. Open http://your-address:3333. This works today. It needs the password, and it only shows sessions you have shared. Any device that can see a session can type into it, and the last one to type is shown as its driver. The connection is plain HTTP, so use a trusted network or a VPN.
  • The AASC phone app. Android is a download on the phone page; the iPhone app will come through TestFlight. It pairs with a code instead of a password. Pair a phone or computer is in the devices menu from 2.10.60; on older versions, set phonePairing to true.
  • Another computer's AASC. The desktop app can pair with AASC on another computer, such as a Linux box or a second Mac, and open that computer's dashboard in a window of its own. On the other computer, open the devices menu, choose Pair a phone or computer and click Copy link. On this one, open the devices menu, then Remote computers, Add a computer, and paste the link. Check that both show the same code, then press Allow on the other computer. A paired computer sees only that computer's shared sessions, like a password sign-in, and can be revoked there like a phone.

A paired phone can reach your computer over Tailscale from any network. Install Tailscale on your computer and sign in. In the dashboard, RESOURCES, then Cloud, then Remote access shows the Tailscale state and each phone's last connection.

Sessions are hidden from other devices until you share them:

  • The Share button on a session shares that session.
  • Share new sessions with my devices in the devices menu shares every new session from the start. It is off by default.
  • Share all open sessions now shares what is already open.