ai-agent-session-center AGENTS.md

AI Agent Session Center: Agent Guidance

This file is the durable coding-agent entrypoint for this repository. It is based on CLAUDE.md; read CLAUDE.md for the full architecture notes and keep the two files aligned when project guidance changes.

Project Snapshot

AI Agent Session Center is a localhost dashboard on port 3333 for monitoring AI coding agent sessions from Claude Code, Codex, and related tools. It uses hooks to ingest session events, visualizes sessions as 3D robots, supports SSH terminals, team/subagent tracking, prompt queuing, workspace snapshots, and session resume.

Core stack:

• Backend: Node.js 18+, ESM, Express 5, ws 8, tsx
• Frontend: React 19, Three.js / @react-three/fiber, Zustand 5, Vite 7
• Desktop: Electron 34, electron-builder 25
• Terminal: node-pty through Electron IPC, WebSocket fallback in browser
• Hooks: Bash hook script with JSONL file queue and HTTP POST fallback
• Persistence: SQLite / better-sqlite3 on the server, IndexedDB / Dexie in the browser

Common Commands

npm run dev              # Vite + tsx watch
npm run build            # Production build
npm start                # Start production server
npm test                 # Vitest
npm run test:e2e         # Playwright E2E
npm run test:coverage    # Coverage report
npm run typecheck        # tsc --noEmit (src/ only)
npm run typecheck:server # tsc --noEmit -p tsconfig.server.json (server/ + src/types)
npm run typecheck:all    # both, in sequence
npm run lint             # ESLint src/
npm run format           # Prettier
npm run electron:dev     # Build and launch Electron app
npm run electron:build   # Build distributables
npm run install-hooks    # Install CLI hooks
npm run uninstall-hooks  # Remove dashboard hooks
npm run setup            # Interactive setup wizard
npm run reset            # Remove hooks, clean config, backup

Use the smallest verification command that fits the change. For shared contracts, state shape, server routes, Electron IPC, terminal behavior, or feature-doc work, prefer at least npm run typecheck:all (plain typecheck only covers src/ — server/ has its own tsconfig.server.json and nothing runs it automatically, so a server-only change checked with plain typecheck can still ship a type error) plus any targeted tests that cover the touched area.