Português | English
Pixel-art visual dashboard for orchestrating and monitoring AI agents (AITEAM-X) in real time.
npx aiteam-x@latestAITEAM-X is an interactive dashboard that turns AI agent management into a visual, intuitive experience. Inspired by sim manager-style simulation games, the panel displays agents as pixel-art characters in a virtual office, allowing you to:
- Visualize each agent's status and location in real time in the 2D pixel-art virtual office
- Customize the experience with 4 visual themes (Pixel Bots, Chibi, Hybrid, Teams) — each with distinct palettes and avatars
- Interact directly with agents through a resizable lateral chat drawer with SSE streaming
- Create rooms to group agents into custom work contexts
- Review diffs of files modified by agents with inline approval/rejection before persisting changes
- Orchestrate workflows such as Party Mode and brainstorming sessions via the workflow panel
- Monitor usage metrics via a gamified Quest Log (messages, tokens in/out) and view tool calls in real time
- Observe platform health and recent events via the Observability page (Help menu → 📡): API snapshot, JSONL log under
.aiteam/, optional browser console capture (dev / localhost) - Persist context and memories between work sessions with LLM extraction, compaction, and automatic migration
- Update the platform with one click via integrated self-update (check, download, merge, restart)
The project loads agent definitions from the aiteam-x-agents/ pack in the project, natively integrating with the Cursor Agent CLI and Cursor ACP (Agent Client Protocol) for bidirectional LLM communication.
Virtual office with Jarvis Office, Kitchen, and individual workspaces. Bottom bar with avatars and sprint progress (14/14 — 100%).
Real-time conversation window with BMad Master. Each agent responds with text streaming and Markdown support.
Per-agent memory management panel. Categories: decisions, lessons, tasks, projects, handoffs. Real-time BM25 search.
Status filters (All / Working) and Module filters (BMGD / BMM / CORE) for segmented agent views.
- Collapsible sidebar: lateral navigation with agents organized by module, custom rooms, and real-time status indicators
- Shared rooms: Jarvis Office, Kitchen — with agent activity context
- Individual workspace grid per agent with module indicators (BMGD / BMM / CORE / BMB)
- Pixel art or image-based avatars (depending on theme) with real-time visual status
- Bottom bar with compact avatars and sprint timeline with granular per-story progress
- Day/night cycle and ambient effects (2D)
- Starfield Canvas: background animation with stellar particles as a decorative visual effect
- Agent selection (click) or multi-selection (Ctrl+click) for batch commands
- Chat Drawer: resizable panel pinned to the right with real-time SSE streaming (replaced floating windows)
- Per-agent input history (↑ to navigate previous commands)
- Rich Message Rendering: responses segmented into Markdown, terminal blocks, tool call indicators, and collapsible thinking blocks
- Thinking Block: expandable view of the model's internal reasoning (chain-of-thought)
- Tool Call Indicators: real-time badges showing agent actions (Read, Edit, Terminal, Grep, etc.) with contextual summaries
- Copy button: appears on hover over agent responses for one-click copy
- Context menu: right-click on any agent to see agent-specific MDC commands
- Stop button to cancel ongoing processing
- Conversation history persisted across reloads
- Escape shortcut to close the drawer
- Pre-command snapshot: the system captures file state before each agent command and compares after the response, detecting changes with precision
- Inline diff cards: unified diff cards appear directly in the agent conversation with per-line syntax highlighting (additions, removals, context)
- Granular approval: Approve/Deny buttons per individual file, or "Approve All" for batch acceptance
- Automatic revert: denied files are reverted to their original content via
/api/files/revert - Visual counters of added/removed lines per file and status badges (Approved / Reverted)
- 4 visual themes: Pixel Bots (cyberpunk), Chibi (anime), Hybrid (tech), Teams (corporate)
- Dynamic avatars: Chibi and Hybrid themes use image-based avatars; Pixel Bots and Teams use SVG pixel art
- ThemePicker: visual selector with color preview and icon per theme
- Persistence: selected theme saved in
localStorageand applied via CSS custom properties
- Free creation: group any combination of agents into themed rooms via
CreateRoomModal - Integrated sidebar: rooms appear in the side bar with icon and member list
- RoomTransition: smooth transition animation when switching between rooms
- API persistence: rooms saved on the server (
/api/rooms) and synchronized across reloads
- Gamified panel: RPG-style visualization of each agent's activities
- Per-agent status: active (in conversation), complete (last session), idle (no activity)
- Metrics: message count, tokens consumed, and last message sent
- Inline avatar: each quest displays the corresponding agent's pixel art avatar
- Model Bar: LLM model selection applied to all agents
- Cursor ACP: dynamic submenu listing all models available in the user's Cursor account (Claude, GPT, Gemini, Grok, etc.)
- Direct models: Composer 2, Claude Opus/Sonnet, GPT-5.x, Gemini, Grok, Kimi
- Status Filter: All / Working — displays real-time counter (e.g. 14/14)
- Module Filter: BMGD / BMM / CORE — segments agents by area
- Direct communication with Cursor via JSON-RPC 2.0 over stdio (
agent acp) - Automatic discovery of available models via ACP session
configOptions - Per-session model switching via
session/set_config_option - Persistent ACP process with 30-min session TTL and automatic reconnection
- Streaming tool calls with rich metadata (type, title, summarized output)
- Error fallback with actionable messages for the user
- Automatic detection of Party Mode and active workflows
- Agents dynamically move to rooms according to the workflow
- Session state persisted on disk and synchronized via SSE
- Per-agent message and token metrics
- Memory Vault: full visual panel with 5 categories (decisions, lessons, tasks, projects, handoffs)
- Auto-extract via LLM: when closing a session, the system analyzes the conversation and automatically extracts structured memories
- Badge 🤖 llm: automatically extracted entries are flagged for 10 minutes with veto option
- BM25 Search: relevance-based semantic search within each agent's vault
- Context Injection: relevant memories automatically injected when starting new sessions (2,000-token budget)
- Automatic compaction:
/api/memory/compactcleans old checkpoints, merges duplicates, and rebuilds indexes - Data migration:
/api/memory/migrateupdates data structures from previous versions automatically - Auto-save: conversations saved every 30s + save on unload via
sendBeacon - Session Checkpoint: history preserved even across unexpected restarts
- Shared Memory:
_project.mdinjected into all agents as global context
- Automatic check:
/api/version/checkcompares local version with the NPM registry - UpdateModal: step-by-step interface with visual progress (download → merge → install → restart)
- Smart merge: updates only template files without overwriting local configurations
- Automatic restart: restarts the development server after the update
- Event Toast: visual notification system with 4 types (success, error, info, milestone) and auto-dismiss
- Easter Eggs: hidden interactions in the virtual office (fridge, coffee machine, and more) with rarities (common, rare, legendary)
- Sound system: optional sound effects for interactions and discoveries
- Dynamic Discovery: automatically detects agents via CSV/YAML — no hardcoding
- Cross-platform: works on Windows, macOS, and Linux
- Web Setup Wizard:
/setupin the browser — 3 animated phases: machine scan, review, step-by-step configuration - CLI Setup Wizard:
npm run setup— interactive terminal alternative (6 steps) - Health Gate: if not configured, automatically redirects to
/setup - Flexible Config: local
aiteam.config.json+AITEAM_AGENTS_ROOTorAITEAM_BMAD_ROOTfor external/CI instances
| Layer | Technology | Version |
|---|---|---|
| Framework | Next.js (App Router) | 15.x |
| UI | React | 19.x |
| Language | TypeScript | 5.x |
| Styling | CSS custom (design system with 4 themes) | — |
| Font | VT323 (Google Fonts) | — |
| Backend | Next.js API Routes + SSE (23 route handlers) | — |
| Diff Engine | diff (npm) | 8.x |
| Search | MiniSearch (BM25) | 7.2.x |
| Agents | Cursor Agent CLI + ACP | latest |
| Protocol | ACP (JSON-RPC 2.0 / stdio) | v1 |
| Parsing | yaml (npm) | 2.8.x |
| Tests | Vitest + v8 coverage | 4.x |
| Agents pack | aiteam-x-agents/ + manifests |
— |
| Requirement | Required | Notes |
|---|---|---|
| Node.js >= 18 | Yes | node --version |
aiteam-x-agents/ agents pack |
Yes | See Installation Guide |
| Cursor IDE | Yes | Generates the Cursor Agent CLI on first launch |
| Git | Yes | — |
Supported platforms: Windows 10/11, macOS, Linux
Option 1 — One command (recommended):
npx aiteam-x@latestCreates the project in the current directory (must be empty). Or specify a folder name:
npx aiteam-x@latest my-projectThe command downloads the template, installs dependencies, runs the setup wizard, and starts the server automatically.
Option 2 — Manual installation:
# 1. Clone the repository
git clone https://github.com/INOSX/AITeam.git
cd AITeam
# 2. Install dependencies
npm install
# 3. Run the setup wizard
npm run setup
# 4. Start the development server
npm run devThe dashboard will be available at http://localhost:3000.
If setup hasn't been completed, the system automatically redirects to
http://localhost:3000/setup— an animated wizard that detects the environment, shows what's ready, and lets you configure everything through the browser.
CLI alternative:
npm run setupruns the interactive wizard in the terminal.
| Command | Description |
|---|---|
npm run setup |
Interactive setup wizard (first install) |
npm run dev |
Start the development server (port 3000) |
npm run dev:clean |
Start with cache cleanup (resolves state issues) |
npm run build |
Generate the production build (with pre-build validations) |
npm run start |
Start the production server |
npm run lint |
Run the linter (ESLint) |
npm run test |
Run tests with Vitest |
npm run test:watch |
Tests in watch mode (re-runs on save) |
| Script | Description |
|---|---|
node scripts/import-conversations.mjs |
Import conversation history into the vault |
node scripts/generate-chibi-logo.mjs |
Generate chibi-style logo assets |
node scripts/crop-avatars.mjs |
Crop avatars for image-based themes |
All scripts require the server running at
localhost:3000.
AITEAM-X/
├── app/ # Next.js App Router
│ ├── api/ # API Routes (backend) — 23 route handlers
│ │ ├── acp/
│ │ │ └── models/route.ts # GET: available models via ACP
│ │ ├── agents/
│ │ │ ├── route.ts # GET: list agents with status
│ │ │ ├── command/route.ts # POST: send command via SSE (CLI or ACP) + file diffs
│ │ │ └── menus/route.ts # GET: agent context menus
│ │ ├── bridge/route.ts # GET: ACP health check
│ │ ├── aiteam-config/route.ts # GET: app flags (e.g. provider APIs)
│ │ ├── files/
│ │ │ └── revert/route.ts # POST: revert file to original content (diff denial)
│ │ ├── memory/
│ │ │ ├── route.ts # GET/POST: memory and conversations (legacy)
│ │ │ ├── vault/route.ts # GET/POST/PUT/DELETE: structured vault
│ │ │ ├── search/route.ts # GET: BM25 search
│ │ │ ├── checkpoint/route.ts # POST: session checkpoint
│ │ │ ├── compact/route.ts # POST: data compaction (cleanup + merge + reindex)
│ │ │ └── migrate/route.ts # POST: data structure migration from previous versions
│ │ ├── rooms/route.ts # GET/POST: custom agent rooms
│ │ ├── session/
│ │ │ ├── route.ts # GET/POST: active session
│ │ │ └── stream/route.ts # GET: SSE for session changes
│ │ ├── sprint/route.ts # GET/POST: sprint status
│ │ ├── terminal/
│ │ │ └── execute/route.ts # POST: terminal command execution
│ │ ├── version/
│ │ │ ├── check/route.ts # GET: check latest version on NPM
│ │ │ ├── update/route.ts # POST: SSE download + merge + install
│ │ │ └── restart/route.ts # POST: restart the dev server
│ │ └── workflows/route.ts # GET: available workflows
│ ├── actions/
│ │ └── setup-save.ts # Server Action: saves aiteam.config.json
│ ├── setup/
│ │ ├── page.tsx # Setup page (health gate + Server Component)
│ │ └── SetupWizard.tsx # Animated 3-phase wizard (Client Component)
│ ├── globals.css # Design system with 4 themes (800+ lines)
│ ├── layout.tsx # Root layout (VT323, pt-BR)
│ ├── error.tsx # Error boundary
│ └── page.tsx # Main page (health gate)
│
├── components/ # React Components (~49 files)
│ ├── rooms/ # Virtual office rooms (2D)
│ │ ├── ConferenceRoom.tsx
│ │ ├── JarvisOffice.tsx
│ │ └── Kitchen.tsx
│ ├── AgentContextMenu.tsx # Per-agent context menu
│ ├── AgentDetail.tsx # Detailed agent view
│ ├── AgentListItem.tsx # Sidebar list item
│ ├── AgentsProvider.tsx # Global Context Provider
│ ├── BottomBar.tsx # Bottom bar with avatars and sprint
│ ├── ChatDrawer.tsx # Resizable lateral chat drawer + inline diffs
│ ├── CommandPopup.tsx # Multi-agent popup
│ ├── CopyButton.tsx # Copy button for responses
│ ├── CreateRoomModal.tsx # Modal for creating custom rooms
│ ├── DayNightCycle.tsx # Day/night cycle (2D)
│ ├── DiffViewer.tsx # Diff viewer with inline approval/rejection
│ ├── EasterEggs.tsx # Hidden office interactions
│ ├── EventToast.tsx # Toast notification system
│ ├── FilterContext.tsx # Filter context (status + module)
│ ├── Layout.tsx # Main shell
│ ├── MainContent.tsx # Main orchestrator
│ ├── MarkdownRenderer.tsx # Custom Markdown renderer
│ ├── MemoryVault.tsx # Memory Vault dashboard (modal)
│ ├── MessageRenderer.tsx # Segmented renderer (MD, terminal, tools, thinking)
│ ├── ModelBar.tsx # Model selection bar and filters
│ ├── PixelAvatar.tsx # Pixel art SVG / image-based avatar
│ ├── QuestLog.tsx # Gamified agent activity panel
│ ├── RoomTransition.tsx # Room transition animation
│ ├── Sidebar.tsx # Collapsible sidebar (agents + rooms)
│ ├── SpeechBubble.tsx # Individual speech bubble
│ ├── SpeechBubbleOverlay.tsx # Chat overlay system
│ ├── SprintPanel.tsx # Dedicated sprint panel
│ ├── StarfieldCanvas.tsx # Background stellar particle animation
│ ├── TerminalBlock.tsx # Terminal block in responses
│ ├── ThemePicker.tsx # Visual theme selector
│ ├── ThemeProvider.tsx # Theme context provider
│ ├── ThinkingBlock.tsx # Collapsible reasoning block (thinking)
│ ├── ThinkingBubble.tsx # Animated thinking indicator
│ ├── ToolCallIndicator.tsx # Real-time tool call badge
│ ├── TopBar.tsx # Top bar with title and controls
│ ├── UpdateModal.tsx # Self-update modal with step-by-step progress
│ ├── WorkflowPanel.tsx # Workflow panel with module filter
│ ├── WorkspaceCell.tsx # Individual workspace cell
│ ├── WorkspaceGrid.tsx # Workspace grid
│ └── WorkspaceProps.tsx # Shared workspace props
│
├── lib/ # Business logic and utilities
│ ├── acp-client.ts # ACP client (JSON-RPC 2.0 over stdio)
│ ├── acp-manager.ts # ACP session manager
│ ├── aiteam-config.ts # Config loader (env var > file > defaults)
│ ├── diff.ts # Unified diff engine (computeUnifiedDiff)
│ ├── health.ts # Health check: agents pack, Cursor CLI, config
│ ├── mock-agents.ts # Mock data for testing and preview
│ ├── model-config.ts # Available LLM model options
│ ├── parseMultiAgentResponse.ts # Multi-agent response parser
│ ├── setup-discovery.ts # Extended discovery for the web wizard
│ ├── sound.ts # Sound effects system
│ ├── synergy.ts # Agent synergy logic
│ ├── theme.ts # Theme definitions (4 themes + metadata)
│ ├── types.ts # Global TypeScript types
│ ├── useAgents.ts # Agent management hook
│ ├── version.ts # Version check (NPM registry)
│ ├── bmad/ # TS parsers (`lib/bmad/`); on-disk pack: `aiteam-x-agents/`
│ │ ├── discovery.ts # Pack scanner + Cursor CLI detection
│ │ ├── agent-mapping.ts # Manifest → Agent mapping
│ │ ├── chat-sessions.ts # Chat session persistence
│ │ ├── memory-bank.ts # Memory bank integration
│ │ ├── parse-agents.ts # agent-manifest.csv parser
│ │ ├── parse-config.ts # config.yaml parser
│ │ ├── parse-persona.ts # Persona (.mdc) parser
│ │ ├── parse-session.ts # Session state + SSE
│ │ ├── parse-sprint.ts # sprint-status.yaml parser
│ │ └── parse-workflows.ts # Workflows parser
│ └── memory/ # Memory system v2.2
│ ├── compact.ts # Data compaction and cleanup
│ ├── inject.ts # Context injection (BM25 + budget)
│ ├── migrate.ts # Cross-version structure migration
│ ├── search.ts # BM25 search engine
│ ├── session.ts # Session lifecycle (sleep/recover)
│ ├── types.ts # Memory system types
│ ├── vault.ts # Structured vault CRUD
│ └── __tests__/ # Unit tests (Vitest)
│ ├── inject.test.ts
│ ├── session.test.ts
│ ├── vault.test.ts
│ ├── search.test.ts
│ └── migrate.test.ts
│
├── .memory/ # Memory Bank (persistent, gitignored)
│ ├── _project.md # Global context — injected into all agents
│ ├── {agent-id}.md # Individual memory bank per agent
│ ├── conversations/ # Conversation history (JSON)
│ └── .vault/ # Structured vault and extraction queue
│
├── docs/ # Project documentation
│ ├── index.md # Main documentation index
│ ├── screenshots/ # UI screenshots
│ ├── project-overview-aiteam-x.md # Project overview (generated)
│ ├── architecture-aiteam-x.md # Detailed architecture (generated)
│ ├── api-contracts-aiteam-x.md # API contracts — 23 route handlers (generated)
│ ├── component-inventory-aiteam-x.md # Component inventory (generated)
│ ├── development-guide-aiteam-x.md # Development guide (generated)
│ ├── source-tree-analysis.md # Source tree analysis (generated)
│ ├── installation-guide.md # Full installation guide
│ ├── architecture.md # Shortcut → architecture-aiteam-x.md
│ ├── api-reference.md # Shortcut → api-contracts-aiteam-x.md
│ ├── developer-guide.md # Shortcut → development-guide-aiteam-x.md
│ ├── user-guide.md # End-user guide
│ ├── memory-system.md # Memory system technical architecture
│ ├── memory-system-guide.md # Memory system functional guide
│ ├── memory-system-comparison.md # Memory system comparative analysis
│ ├── agent-catalog.md # Complete agent catalog
│ ├── sprint-status.yaml # Current sprint status
│ └── superpowers/ # Future features (specs + plans)
│ ├── specs/ # Design documents
│ └── plans/ # Implementation plans
│
├── hooks/ # Custom React hooks
│ └── useVersionCheck.ts # Version check hook (NPM registry)
│
├── scripts/ # Utility scripts
│ ├── setup.mjs # Interactive setup wizard (6 steps)
│ ├── cli.mjs # CLI for npx aiteam-x (package entry point)
│ ├── safe-build.mjs # Safe build with pre-build validations
│ ├── clean-start.mjs # Dev server with cache cleanup
│ ├── import-conversations.mjs # History import into vault
│ ├── generate-chibi-logo.mjs # Chibi logo asset generation
│ └── crop-avatars.mjs # Avatar cropping for image-based themes
│
├── aiteam.config.example.json # Configuration example (reference)
├── .cursor/ # Cursor IDE rules and skills
│ └── rules/aiteam-x/ # Cursor rules (.mdc): pack agents and workflows
│
├── package.json
├── tsconfig.json
├── next.config.ts
└── .gitignore
| Document | Level | Description |
|---|---|---|
| Documentation Index | All | Main entry point for all documentation |
| Project Overview | Executive | Executive summary, stack, metrics, and features |
| Detailed Architecture | Architectural | Patterns, decisions, diagrams, and layers |
| API Contracts | Technical | 23 route handlers with request/response schemas |
| Component Inventory | Technical | ~47 .tsx components, hierarchy, state, and patterns |
| Development Guide | Developer | Setup, commands, conventions, and troubleshooting |
| Source Code Analysis | Technical | Annotated structure with purpose of each directory |
| Document | Level | Description |
|---|---|---|
| Installation Guide | Beginner | Step-by-step installation, setup wizard, troubleshooting |
| Architecture (shortcut) | — | Points to architecture-aiteam-x.md |
| API (shortcut) | — | Points to api-contracts-aiteam-x.md |
| Developer (shortcut) | — | Points to development-guide-aiteam-x.md |
| User Guide | End User | How to use the dashboard, interact with agents, Memory Vault |
| Memory System (technical) | Technical/Conceptual | Layered architecture of the memory system |
| Memory Guide (functional) | End User | How to use the Memory Vault, case studies, best practices |
| System Comparison | Technical | Comparative analysis of memory systems |
| Agent Catalog | Reference | All agents, specialties, and how to work with each one |
The system automatically discovers agents from aiteam-x-agents/_cfg/agent-manifest.csv. The default installation includes 14 agents:
| Persona | Role | Module |
|---|---|---|
| BMad Master | Main orchestrator, knowledge custodian | core |
| BMad Builder | Pack module, agent, and workflow creation | core |
| Mary | Business Analyst — research and business requirements | bmm |
| John | Product Manager — PRD, epics, product management | bmm |
| Winston | Architect — system architecture and tech spec | bmm |
| Sally | UX Designer — experience and interface design | bmm |
| Bob | Scrum Master — sprint planning and code review | bmm |
| Amelia | Developer — story and feature implementation | bmm |
| Murat | Test Architect — testing strategy and design | bmm |
| Paige | Tech Writer — technical documentation and knowledge | bmm |
| Cloud Dragonborn | Game Architect — game architecture and systems | bmgd |
| Samus Shepard | Game Designer — GDD, narrative, and game design | bmgd |
| Link Freeman | Game Developer — game implementation | bmgd |
| Max | Game Scrum Master — agile management for game dev | bmgd |
See the Agent Catalog for details on each agent's specialties and commands.
AITEAM-X uses a local aiteam.config.json file (gitignored) generated by npm run setup. For advanced configuration, create a .env.local:
# Project root that contains the aiteam-x-agents/ folder (recommended)
# Legacy alias: AITEAM_BMAD_ROOT (same effect)
AITEAM_AGENTS_ROOT=/path/to/your/project
# Overrides the memory directory (useful for testing)
MEMORY_DIR_OVERRIDE=/custom/path/.memoryPriority for agentsRoot (pack root):
AITEAM_AGENTS_ROOT or AITEAM_BMAD_ROOT (env) > aiteam.config.json (`agentsRoot` or legacy `bmadRoot`) > "./"
See the Installation Guide for all configuration scenarios.
- Fork the repository
- Create a branch from
develop(git checkout -b feature/my-feature develop) - Make your changes following project conventions
- Ensure
npm run lintandnpm run buildpass without errors - Open a Pull Request to
develop
Report bugs or suggest improvements? Open an issue on GitHub.
See the Development Guide and Architecture for conventions, workflow, and technical decisions.
This project is distributed under the MIT License. See LICENSE for details.
Mario Mayerle (MaMFLux) — INOSX
AITEAM-X — where AI agents work as a team. | v0.14.5
