ClosedLoop.AI

The open-source workspace for team-based agentic software development.

Quick Start · Architecture · Deployment Guide · Contributing

---

ClosedLoop is a platform where AI agents produce delivery artifacts (PRDs, implementation plans, code) and humans review them at every stage. Define requirements, generate plans, execute to PRs — all in one workspace visible to the whole team.

Quick Start

Prerequisites: Node.js 24+, pnpm, Docker

git clone https://github.com/closedloop-ai/closedloop-ai.git
cd closedloop-ai
pnpm install
docker compose up -d        # Start PostgreSQL
pnpm migrate                # Run database migrations
pnpm dev                    # Start all apps

Open http://localhost:3000.

First run automatically creates .env.local files from .env.example templates. Add your Clerk keys and other credentials — see the Deployment Guide.

Service Accounts

Service	Required	Purpose
Clerk	Yes	Authentication
PostgreSQL	Yes	Database (Docker locally)
GitHub App	For execution	Workflow dispatch
Anthropic	For AI features	Claude API
Liveblocks	For collaboration	Real-time editing
PostHog	Optional	Analytics
Linear	Optional	Issue sync

Common Commands

pnpm dev                                    # Start all apps
pnpm turbo dev --filter=app --filter=api    # Start specific apps
pnpm build                                  # Build everything
pnpm typecheck                              # TypeScript check
pnpm lint                                   # Lint (Biome)
pnpm test                                   # Run tests
pnpm migrate                                # Database migrations

Architecture

Next.js monorepo with Turborepo.

Apps

App	Port	Description
app	3000	Main application — dashboard, editor, workstreams
api	3002	BFF API — database, webhooks, integrations
web	3001	Marketing site
mcp	3010	MCP server for Claude Code CLI
relay	3020	WebSocket relay for desktop compute
storybook	6006	Component library
studio	3005	Prisma Studio — database browser
desktop	—	Electron desktop app — localhost gateway, agent monitor, packaged installer

Packages

Shared packages imported as @repo/<name>:

Package	Purpose
database	Prisma ORM, schema, migrations
api	Shared type definitions
auth	Authentication (Clerk)
ai	Claude integration
github	GitHub App (dispatch, webhooks)
design-system	UI components (Shadcn + Tailwind)
rich-text	TipTap editor with Mermaid
collaboration	Real-time editing (Liveblocks)
analytics	PostHog + Google Analytics
observability	Structured logging
email	Transactional email (Resend)

Desktop App

apps/desktop is an Electron app that runs a localhost gateway for local agent execution, with a built-in agent monitor. It builds and packages directly from this repo:

pnpm desktop:dev          # Run the desktop app in development
pnpm desktop:build        # Build main + renderer bundles
pnpm desktop:package      # Produce a distributable (.dmg + .zip) in apps/desktop/dist-dmg

Packaging produces an unsigned (ad-hoc) build by default — no Apple credentials required. Official signed + notarized releases set the Apple signing env vars (CSC_LINK, CSC_KEY_PASSWORD, APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID). Service origins default to the ClosedLoop cloud and can be overridden via CL_RELAY_ORIGIN, CL_WEB_APP_ORIGIN, and CL_AUTH_API_ORIGIN. See apps/desktop/README.md.

Core Workflow

sequenceDiagram
    participant User
    participant App as ClosedLoop
    participant API as API Server
    participant GH as GitHub Actions
    participant Repo as Target Repo

    User->>App: Create PRD (AI-assisted)
    App->>API: Generate plan
    API->>GH: Dispatch workflow
    GH->>API: Return plan via webhook
    User->>App: Review and approve
    App->>API: Execute plan
    API->>GH: Dispatch execution
    GH->>Repo: Create Pull Request

Loading

Contributing

We welcome contributions. See CONTRIBUTING.md for conventions, code style, and testing requirements.

# Fork on GitHub, then:
git clone git@github.com:YOUR_USERNAME/closedloop-ai.git
cd closedloop-ai
git remote add upstream git@github.com:closedloop-ai/closedloop-ai.git
pnpm install && docker compose up -d && pnpm dev

Documentation

• Local Deployment Guide — Full setup and troubleshooting
• Database Schema — Entity relationships and data model
• GitHub App Setup — Workflow dispatch configuration
• Product Overview — System architecture and API surface

Troubleshooting

Problem	Fix
pnpm typecheck fails with "Property does not exist"	pnpm install && cd packages/database && pnpm prisma generate
Environment variable validation errors	Comment out unused vars (empty "" fails validation)
Database connection issues	docker compose up -d and check DATABASE_URL in .env.local

Legacy Identifiers

Some internal identifiers use "Symphony" (an earlier codename). These don't affect the product and are preserved to avoid breaking runtime behavior — e.g., /api/gateway/symphony/* routes.

License

MIT © 2026 ClosedLoop