Getting Started

Prerequisites#

• Node.js 18+ — Download↗
• jq (recommended) — JSON enrichment for hook events

# 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).

One-Command Install#

npx ai-agent-session-center

This does everything:

1. Downloads and runs the setup wizard (first time only)
2. Installs hook scripts into your CLI config files
3. Starts the dashboard server at http://localhost:3333
4. Opens your browser automatically

Setup Wizard#

On first run, an interactive 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 |

Re-run the wizard anytime with npx ai-agent-session-center --setup.

Your First Session#

1. Start the dashboard — it opens at http://localhost:3333
2. Open a terminal and run your AI CLI (e.g., claude)
3. Watch the dashboard — a 3D robot appears representing your session
4. Click the robot to see full session details, terminal, and prompt history

The robot animates based on what the AI 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

Alternative Install Methods#

Global Install#

npm install -g ai-agent-session-center
ai-agent-session-center

From Source#

git clone https://github.com/coding-by-feng/ai-agent-session-center.git
cd ai-agent-session-center
npm install
npm run dev

CLI Options#

ai-agent-session-center [options]

  --port <number>    Server port (default: 3333)
  --no-open          Don't auto-open browser
  --debug            Enable verbose logging
  --setup            Re-run the setup wizard

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 | | Gemini CLI | ~/.gemini/settings.json | ~/.gemini/hooks/dashboard-hook-gemini.sh | | Codex | ~/.codex/config.toml | ~/.codex/hooks/dashboard-hook-codex.sh |

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