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

🛠 Tech Stack

🏗 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

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

Available Resources

Configuration Options

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.

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:

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.