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 you to set a password. The password is required. Without one, only your own computer can open the dashboard and every other device is refused.

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

When you run from source, npm run setup asks six questions, installs the hooks, and then starts the server. The desktop app has its own setup wizard with similar questions.

  1. Server port. Default 3333.
  2. Which AI CLIs to hook. Default: Claude Code only. You can add Codex.
  3. Hook density. Default: medium. See Configuration.
  4. Debug mode. Default: off.
  5. Session history retention. Default: 24 hours. The choices are 12, 24 and 48 hours, or 7 days.
  6. Dashboard password. Optional in this wizard. A password needs at least 8 characters, with an upper case letter, a lower case letter, a digit and a special character.

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 or codex.
  3. Watch the dashboard. A card for your session appears on the LIVE board. If you turn on the 3D view, a robot appears too. The 3D view is off by default.
  4. Click the session to open its terminal, project files, conversation, notes and queue.

You can also start a session from the dashboard. Click the + in the session panel, or + NEW on the empty LIVE page. See Terminal & SSH.

What the statuses mean

Each status has a colour that follows your theme. For example, idle uses the theme's green and working uses its orange.

  • idle: no activity.
  • prompting: you sent a prompt and the agent is starting on it.
  • working: tools are running.
  • approval: the agent needs your permission for a tool.
  • input: the agent asked you a question and waits for your answer.
  • waiting: the agent finished its turn and waits for your next prompt.
  • ended: the session is over. Its card stays on the board, and you can resume it.

In the optional 3D view, idle and waiting robots go to the coffee lounge, and prompting and working robots sit at a desk. An approval flashes the robot's visor yellow. An input request turns it purple.

Open the dashboard from another device

Other devices on your network can open http://your-address:3333, where your-address is your computer's address and 3333 is your port.

  • A password is required. Without one the server refuses every device except your own computer.
  • Sessions stay hidden from other devices until you share them. Use the Share button on a session, or turn on Share new sessions with my devices in the devices menu in the header.
  • The connection is plain HTTP. Use a trusted network or a VPN. Anyone with the password can run terminals on your computer, so treat it like SSH access.

The AASC phone app is a download for Android on the phone page; the iPhone app will come through TestFlight. From 2.10.60, Pair a phone or computer is in the devices menu; older versions need phonePairing set to true. A phone browser works today with the password and your shared sessions. A paired phone can reach your computer over Tailscale from any network. See Configuration.

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
npm start -- --debug       # verbose logging (same as: npm run debug)

What Gets Installed

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

  • Claude Code: hook entries in ~/.claude/settings.json, and the script ~/.claude/hooks/dashboard-hook.sh (on Windows, dashboard-hook.ps1).
  • Codex: hook entries in ~/.codex/config.toml, and the script ~/.codex/hooks/dashboard-hook.sh.

The hook also sets your terminal tab title and writes the session id to <project>/.claude/last-session-id, so you can resume from a shell.

AASC also copies dashboard-statusline.sh into ~/.claude/hooks/. It is not registered in your settings. AASC passes it only to Claude sessions it starts itself, to read your plan limits, and it still runs your own status line.

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

Your data lives in data/ when you run from source. The desktop app keeps it in its own folder, which on macOS is ~/Library/Application Support/ai-agent-session-center/.