Skip to content
AASC
Documentation pages

Getting Started

Install AASC as a desktop app or from source, and start your first session.

Prerequisites

  • Claude Code, or the Codex CLI 0.130 or later (Codex hooks are opt-in)
  • jq on macOS and Linux, so hook events are matched to the right terminal (the Windows hook uses PowerShell)
# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

Without jq, hooks still work but send unenriched JSON (no PID, TTY, or terminal detection).

Install

There are two ways to run AASC. Both give you the same dashboard.

Desktop app

Download the app for macOS (Apple silicon), Windows or Linux from the download page, which also has the install steps. The server is built in, so you do not need Node.js. A setup wizard installs the hooks and asks for a password.

From source with npm

You need Node.js 22.12 or later and Git.

git clone https://github.com/coding-by-feng/ai-agent-session-center.git
cd ai-agent-session-center
npm install
npm rebuild better-sqlite3 node-pty
npm run build
npm start

npm start registers the hooks every time it starts and opens the dashboard at http://localhost:3333. The npm page has the details.

Setup Wizard

The from-source setup wizard asks 6 questions:

| Step | Question | Default | |------|----------|---------| | 1 | Server port | 3333 | | 2 | Which AI CLIs to hook | Claude only | | 3 | Hook density | Medium (12 events) | | 4 | Debug mode | Off | | 5 | Session history retention | 24 hours | | 6 | Dashboard password | None |

When you run from source, npm run setup runs this wizard and then starts the server. The desktop app has its own setup wizard.

Your First Session

  1. Start the dashboard: it opens at http://localhost:3333
  2. Open a terminal and run your AI CLI (for example claude)
  3. Watch the dashboard: a card for your session appears on the LIVE board (or a robot, if you turn on the 3D view)
  4. Click the session to see its terminal, conversation, files, notes and queue

In the 3D view, each robot shows what its agent is doing:

  • Green idle — no activity, robot hangs out at the coffee lounge
  • Cyan prompting — you sent a prompt, robot walks to a desk
  • Orange working — tools are running, charging effect on the robot
  • Yellow approval — the agent needs your permission, visor flashes

Server Options

When you run from source, pass options after --:

npm start -- --port 4444   # use another port (default: 3333)
npm start -- --no-open     # don't open a browser window

What Gets Installed

The setup process adds hook scripts to your CLI config files:

| CLI | Config File | Hook Script | |-----|------------|-------------| | Claude Code | ~/.claude/settings.json | ~/.claude/hooks/dashboard-hook.sh | | Codex | ~/.codex/config.toml | ~/.codex/hooks/dashboard-hook.sh |

All hooks are installed with "_source": "ai-agent-session-center" so they can be cleanly removed with npm run uninstall-hooks.