openspace.ai

Make human and AI better together. openspace.ai is a web-based squad management tool that gives people a rich, intuitive interface to manage, direct, and collaborate with AI agent teams in real time — including through natural voice conversation. It wraps around the existing .squad/ file system and agent framework, providing a visual dashboard, task board, live activity feed, chat interface, decision log, and real-time group voice chat so anyone — not just engineers — can work with AI teams effectively.

---

✨ Features

Feature	Description
Squad Dashboard	Visual overview of all agents — status, current tasks, queue depth, and recent activity. Auto-refreshes via WebSocket. Agent cards show live work status (🟢 Working / ⏸️ Idle).
Task Management	Kanban board and list views for creating, assigning, prioritizing, and tracking tasks. Drag-and-drop reordering, filters by agent/status/priority, AI-powered task execution, retry button for blocked tasks, and full sync with .squad/ task files.
Chat Interface	ChatGPT-style conversation with assistant-ui — Slack-style agent avatars, markdown rendering, code blocks, copy/reload buttons, suggestion chips, voice dictation, and conversation history as context.
A2A Protocol	Agent-to-Agent protocol support — each agent is discoverable via AgentCard, callable via JSON-RPC, and can delegate work to other agents. External A2A agents can join the squad.
AI Traces	Full observability — every AI call logged with prompt, response, model, agent, task, and duration. OTLP collector receives spans from Copilot CLI. View at /traces.
Dynamic Team	Hire/fire team members via API or UI. New members automatically get .squad/ charter files, A2A endpoints, and agent worker queues. .squad/ files are the source of truth, SQLite is a cache.
Voice Interface	Real-time voice chat with browser speech recognition + TTS. Continuous listening, multi-agent responses, voice-triggered actions.
Real-time Activity Feed	Live chronological stream of agent events — task starts, completions, decisions, errors — pushed via WebSocket.
Decision Log	Browse and search all team decisions with full-text search and filtering.
Mobile Responsive	Full mobile support — collapsible sidebar with hamburger menu, touch-friendly layouts across all pages.

---

🛠 Tech Stack

Layer	Technology
Frontend	Next.js (App Router), React 18, Tailwind CSS, shadcn/ui, assistant-ui (ChatGPT-style chat), TanStack Query
Backend	Fastify, TypeScript, better-sqlite3 (cache/index layer)
AI	GitHub Copilot SDK (@github/copilot-sdk) — server mode via TCP, session retry with exponential backoff
A2A	A2A JavaScript SDK (@a2a-js/sdk) — Agent-to-Agent protocol for inter-agent communication
Real-time	WebSocket (native), file watching via chokidar
Voice	Browser SpeechRecognition + SpeechSynthesis, react-speech-recognition
Observability	OpenTelemetry (@opentelemetry/sdk-node) — OTLP trace collection + custom AI interaction logging
Shared	TypeScript monorepo with shared type contracts (@openspace/shared)
Data Layer	.squad/ file system (source of truth), SQLite (rebuildable cache with FTS5 search)
Build	Turborepo, pnpm workspaces
Quality	ESLint (flat config), Prettier, Husky + lint-staged, Vitest, Playwright

---

🏗 Architecture

openspace.ai is a monorepo with a Next.js frontend, Fastify API backend, and a shared types package. The .squad/ directory on disk is the single source of truth — the backend reads/watches it and serves data to the frontend via REST + WebSocket. SQLite acts as a rebuildable cache for fast queries and full-text search.

┌─────────────────────────────────────────────────────────────┐
│                        Client (Browser)                      │
│  ┌──────────┐  ┌──────────┐  ┌───────┐  ┌───────────────┐  │
│  │Dashboard │  │Task Board│  │ Chat  │  │ Voice + Traces │  │
│  │(agent    │  │(kanban,  │  │(asst- │  │ (speech rec,  │  │
│  │ status)  │  │ retry)   │  │ -ui)  │  │  OTel viewer) │  │
│  └────┬─────┘  └────┬─────┘  └───┬───┘  └───────┬───────┘  │
│       └──────────────┴────────────┴──────────────┘           │
│                          │                                   │
│                   REST + WebSocket                           │
└──────────────────────────┼───────────────────────────────────┘
                           │
┌──────────────────────────┼───────────────────────────────────┐
│                    Fastify API Server                         │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │  REST API    │  │  WebSocket   │  │  A2A Protocol     │  │
│  │  /api/*      │  │  /ws         │  │  /a2a/:agentId    │  │
│  └──────┬───────┘  └──────┬───────┘  └────────┬──────────┘  │
│         │                 │                    │             │
│  ┌──────┴─────────────────┴────────────────────┴──────────┐  │
│  │              Agent Worker Service                       │  │
│  │  Queue per agent → copilot-sdk → AI → result            │  │
│  │  Retry logic, crash recovery, progress streaming        │  │
│  └─────────────────────┬──────────────────────────────────┘  │
│                        │                                     │
│  ┌─────────────────────┴──────────────────────────────────┐  │
│  │  Copilot SDK (server mode via TCP to CLI on port 3100)  │  │
│  │  Session retry • sendAndWait retry • OTLP tracing       │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌────────────────────┐  ┌─────────────────────────────────┐ │
│  │  .squad/ files     │  │  SQLite Cache                   │ │
│  │  (source of truth) │  │  (tasks, chat, team, traces)    │ │
│  └────────────────────┘  └─────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

│ Squad Orchestration Layer │ │ ┌────────────────┼────────────────┐ │ │ │ .squad/ File System │ │ │ │ (agents, tasks, decisions, │ │ │ │ sessions, orchestration log) │ │ │ └─────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────┘

**Key data flow:**
1. The backend watches `.squad/` for file changes (chokidar)
2. Changes are classified into events and pushed to connected clients via WebSocket
3. The frontend displays real-time updates without polling
4. Write operations (task create/update, chat messages) go through the REST API, which writes to `.squad/` files and updates the SQLite cache

---

## 🚀 Getting Started

### Prerequisites

- **Node.js** 22+ 
- **pnpm** 9+ — install via `corepack enable` or `npm install -g pnpm`
- **Copilot CLI** (optional) — for AI-powered agents. Without it, agents use mock responses.

### Quick Start

```bash
# Clone and start everything
git clone https://github.com/your-org/openspace.ai.git
cd openspace.ai
./start.sh

start.sh handles everything: checks Node/pnpm, installs deps, starts Copilot CLI server, launches API + Web.

Manual Setup

# Install dependencies
pnpm install

# Start Copilot CLI server (optional, in a separate terminal)
copilot --headless --port 3100 --model claude-opus-4.6

# Start dev servers
pnpm dev

Environment Variables

# apps/api/.env
COPILOT_CLI_URL=localhost:3100          # Copilot CLI server (TCP, not subprocess)
COPILOT_MODEL=claude-opus-4.6           # Default AI model
COPILOT_OTLP_ENDPOINT=http://localhost:3001  # Traces collected by our server

URLs

Service	URL
Web App	http://localhost:3000
API	http://localhost:3001
LAN Access	http://<your-ip>:3000
Agent Cards (A2A)	http://localhost:3001/.well-known/agent-card.json
Traces	http://localhost:3000/traces

Other Commands

pnpm build        # Production build (both apps)
pnpm lint         # Lint all packages
pnpm typecheck    # TypeScript type checking
pnpm test         # Run unit/integration tests (Vitest)
pnpm e2e          # Run end-to-end tests (Playwright)
pnpm format       # Format code with Prettier

---

📁 Project Structure

openspace.ai/
├── apps/
│   ├── web/                  # Next.js frontend (App Router)
│   │   ├── app/              # Next.js app directory (routes)
│   │   ├── src/
│   │   │   ├── components/   # UI components (dashboard, tasks, chat, voice, etc.)
│   │   │   ├── hooks/        # Custom React hooks
│   │   │   └── lib/          # Utilities and helpers
│   │   └── ...
│   └── api/                  # Fastify backend
│       └── src/
│           ├── routes/       # REST API route handlers
│           ├── services/     # Business logic (file watcher, WebSocket, DB, activity)
│           ├── lib/          # Shared utilities (parsers, writers)
│           └── ...
├── packages/
│   └── shared/               # @openspace/shared — shared TypeScript types & constants
│       └── src/              # Agent, Task, Decision, Chat, Voice, Activity types
├── docs/
│   ├── prd.md                # Product Requirements Document
│   ├── execution-plan.md     # Phased execution plan
│   └── pending-approval-workflow.md  # Pending-approval task lifecycle & API
├── e2e/                      # Playwright end-to-end tests
├── .squad/                   # Squad file system (source of truth)
│   ├── agents/               # Agent charters and history
│   ├── tasks/                # Task files (YAML frontmatter + markdown)
│   ├── decisions.md          # Decision log
│   ├── team.md               # Team roster
│   └── ...
├── turbo.json                # Turborepo pipeline config
├── pnpm-workspace.yaml       # pnpm workspace definition
└── package.json              # Root workspace scripts

---

🔌 MCP Server

openspace.ai exposes a Model Context Protocol (MCP) server so external AI tools — Claude Desktop, Cursor, VS Code Copilot — can interact with your squad directly.

Connecting to the MCP Server

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "openspace": {
      "command": "npx",
      "args": ["--yes", "-w", "packages/mcp-server", "openspace-mcp"],
      "env": {
        "OPENSPACE_API_URL": "http://localhost:3001"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "openspace": {
      "command": "npx",
      "args": ["--yes", "-w", "packages/mcp-server", "openspace-mcp"],
      "env": {
        "OPENSPACE_API_URL": "http://localhost:3001"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json or .copilot/mcp-config.json:

{
  "mcpServers": {
    "openspace-stdio": {
      "command": "npx",
      "args": ["--yes", "-w", "packages/mcp-server", "openspace-mcp"],
      "env": {
        "OPENSPACE_API_URL": "http://localhost:3001"
      }
    }
  }
}

SSE Transport (Remote / Shared)

For remote or multi-client setups, start the SSE server and point clients at it:

# Start SSE server (default port 3002)
pnpm --filter @openspace/mcp-server start:sse

# Or with a custom port
MCP_PORT=8080 pnpm --filter @openspace/mcp-server start:sse

Then configure clients with the SSE URL:

{
  "mcpServers": {
    "openspace": {
      "type": "sse",
      "url": "http://localhost:3002/sse"
    }
  }
}

Available Tools

Tool	Description	Example
list_agents	List all squad agents with status and current tasks	"Show me the squad"
get_agent	Get detailed info about a specific agent	"What is Bender working on?"
list_tasks	List tasks, filter by status or assignee	"Show all in-progress tasks"
get_task	Get task details	"Get details on task-ABC123"
create_task	Create and assign a new task	"Create a P1 task for Fry to fix the dashboard"
update_task_status	Change task status	"Mark task-ABC123 as done"
list_decisions	List or search squad decisions	"Find decisions about auth"
send_chat_message	Send a message to an agent or the team	"Tell Leela we're ready for review"
get_squad_status	High-level squad overview	"What's the team status?"

Available Resources

URI	Description
openspace://squad	Current squad overview
openspace://agents	Full agent roster
openspace://tasks	Current task board
openspace://decisions	Squad decision log

Configuration Options

Variable	Default	Description
OPENSPACE_API_URL	http://localhost:3001	URL of the openspace.ai API server
MCP_PORT	3002	Port for the SSE transport server

Transport modes:

• stdio (default) — launched by the client as a subprocess. Best for local, single-user setups (Claude Desktop, Cursor, VS Code).
• SSE — runs as an HTTP server. Best for remote access, shared environments, or multi-client setups.

---

📡 API Reference

All endpoints are prefixed with /api. The API runs on port 3001 by default.

Method	Endpoint	Description
GET	/api/health	Health check — returns status and timestamp
GET	/api/agents	List all agents with status, role, and current task
GET	/api/agents/:id	Get agent detail (charter, history, expertise)
GET	/api/tasks	List tasks (filterable by status, assignee, priority)
GET	/api/tasks/:id	Get task detail
POST	/api/tasks	Create a new task
PUT	/api/tasks/:id	Update a task
PATCH	/api/tasks/:id/status	Update task status
PATCH	/api/tasks/:id/priority	Reorder task priority (sortIndex)
DELETE	/api/tasks/:id	Delete a task
PATCH	/api/tasks/:id/approve	Approve a pending-approval task → moves to backlog
PATCH	/api/tasks/:id/reject	Reject a pending-approval task → deletes it
GET	/api/decisions	List all decisions (newest first)
GET	/api/decisions/search	Full-text search decisions (?q=query)
GET	/api/decisions/:id	Get decision detail
GET	/api/squad	Squad overview / dashboard summary
GET	/api/activity	Paginated activity history (?limit=&offset=)
POST	/api/chat/messages	Send a chat message
GET	/api/chat/messages	Get message history (filterable by agent, threadId)

WebSocket: Connect to ws://localhost:3001 for real-time events. Events follow the { type, payload, timestamp } envelope format. Supported event types include task updates, decision additions, agent status changes, and chat messages.

---

🎙 Voice Chat

openspace.ai's voice interface is a real-time, multi-party group voice conversation with your AI squad — like being in a meeting room with your team.

How It Works

1. Start a voice session from the /voice page
2. Talk naturally — the microphone is always listening (Voice Activity Detection handles turn boundaries automatically)
3. The Coordinator routes your speech to the right agent(s) using LLM-based intent classification
4. Agents respond by voice — each agent has a distinct voice profile so you can tell them apart by sound:
   • Leela — confident and direct (nova)
   • Fry — enthusiastic and friendly (echo)
   • Bender — blunt and matter-of-fact (onyx)
   • Zoidberg — methodical and precise (shimmer)
5. Multi-agent responses are supported — ask "What's the status?" and Leela gives the summary, Bender adds a backend update, Fry mentions a frontend blocker
6. Voice commands trigger real actions — "Bender, create an auth endpoint" actually creates a task and assigns it

Architecture

The voice pipeline uses the OpenAI Realtime API over a persistent WebSocket connection:

User speaks → [Browser VAD] → [Audio Stream via WebSocket] → [Realtime STT]
  → [Coordinator / Agent Router] → [Agent Response] → [Streaming TTS]
  → [Audio Stream via WebSocket] → Speaker

• Target latency: < 2 seconds from end-of-speech to start-of-agent-audio
• Text fallback: Every voice interaction has a text equivalent — voice is additive, never required
• Session history: All voice sessions are preserved with full transcripts

---

👥 Team

openspace.ai was built by the openspace.ai squad — a team of AI agents orchestrated via the .squad/ framework:

Agent	Role	Personality
Leela	Lead	Strategic, decisive, keeps the team focused. Authored the PRD, execution plan, and coordinates all work.
Fry	Frontend Dev	Enthusiastic, creative. Built the Next.js frontend — dashboard, task board, chat UI, voice interface.
Bender	Backend Dev	Blunt, efficient, gets things done. Built the Fastify API, data layer, WebSocket pipeline, voice backend.
Zoidberg	Tester	Methodical, thorough. Wrote the test suite — unit, integration, and E2E coverage across the full stack.

Owner: Matanel Cohen

---

🤝 Contributing

Contributions are welcome! Here's how to get started:

Development Workflow

1. Fork and clone the repository
2. Create a feature branch from main: git checkout -b feat/my-feature
3. Install dependencies: pnpm install
4. Make your changes — follow the existing code patterns and conventions
5. Run checks before committing:

   pnpm lint && pnpm typecheck && pnpm test
   

6. Commit with clear, descriptive messages
7. Open a pull request against main

Guidelines

• TypeScript only — no plain JavaScript
• Tests required — every feature or bug fix should include test coverage
• Lint clean — Husky pre-commit hooks enforce linting and formatting
• Types first — if you're adding new data shapes, start in packages/shared
• .squad/ is sacred — the file system is the source of truth. Never bypass it in favor of SQLite-only storage.
• Keep it accessible — UI components should follow WAI-ARIA guidelines

Architecture Principles

• The frontend renders data and manages UI state; it never reads .squad/ directly
• The backend owns all file system access and serves data via REST + WebSocket
• Shared types in packages/shared are the contract between frontend and backend
• SQLite is a rebuildable cache — if you delete it, it reconstructs from .squad/ files

---

📄 License

This project is private and proprietary. All rights reserved.