GSD-2 Mission Control

A full-stack application for managing GSD-2 (Get Shit Done v2) projects, milestones, and runs with autonomous Docker workers, Git integration, and LLM-assisted project analysis.

Features

Core Features

• Project Management: Create and manage projects with Git repository integration
• Milestones: Track progress with milestones and issue grouping
• Runs: Execute autonomous runs to process GitHub issues
• Git Integration: Clone repos, manage branches, fetch issues, create commits
• LLM-Assisted Analysis: Analyze projects with LLM providers (OpenAI, Gemini, Kimi, Ollama, and any OpenAI-compatible API) for insights and recommendations

Advanced Features

• Best-Of Mode: Multiple attempts per issue with automatic selection of the best result
• Docker Worker Containers: Autonomous workers that pull repos, execute tasks, and push results
• AGENTS.md Configuration: Customize agent behavior and workflows per project
• MCP (Model Context Protocol) Support: Extensible AI model integration
• Memory Layers: Optional memory systems for enhanced performance
• Real-time Notifications: WebSocket-based updates for run progress and worker status
• Mission Control Dashboard: Monitor system health, active runs, and worker status

Architecture

Frontend (React + TypeScript)

• Modern React with TypeScript
• Tailwind CSS + shadcn/ui components
• Zustand for state management
• React Query for data fetching
• WebSocket client for real-time updates

Backend (Express + TypeScript)

• RESTful API with Express
• SQLite database with TypeORM
• Git integration with simple-git
• LLM service with OpenAI
• Docker service for container management
• WebSocket server for real-time communication

Docker Worker

• Autonomous Node.js container
• Git operations (clone, branch, commit, push)
• Agent executor with LLM integration
• Attempt tracking with metrics
• Health check and heartbeat system

Quick Start

Prerequisites

• Node.js 20+
• Docker
• Git
• OpenAI API key (for LLM features)
• GitHub token (for private repos)

Frontend

cd app
npm install
npm run dev

Backend

cd server
npm install
cp .env.example .env
# Edit .env with your API keys
npm run dev

Docker Worker

cd docker-worker
npm install
docker build -t gsd2-worker .

API Endpoints

Projects

• GET /api/projects - List all projects
• POST /api/projects - Create a new project
• GET /api/projects/:id - Get project details
• PUT /api/projects/:id - Update project
• DELETE /api/projects/:id - Delete project
• POST /api/projects/:id/analyze - Analyze project with LLM
• GET /api/projects/:id/issues - Fetch GitHub issues

Milestones

• GET /api/milestones - List milestones
• POST /api/milestones - Create milestone
• PUT /api/milestones/:id - Update milestone
• POST /api/milestones/:id/complete - Complete milestone

Runs

• GET /api/runs - List runs
• POST /api/runs - Create run
• POST /api/runs/:id/start - Start run execution
• POST /api/runs/:id/cancel - Cancel run
• GET /api/runs/:id - Get run details with logs and attempts

Workers

• GET /api/workers - List workers
• POST /api/workers/register - Register new worker
• POST /api/workers/:id/heartbeat - Worker heartbeat
• POST /api/workers/:id/release - Release worker

Dashboard

• GET /api/dashboard/stats - Get dashboard statistics
• GET /api/dashboard/health - Get system health

Configuration

AGENTS.md Format

version: "1.0.0"
agents:
  - id: developer
    name: Developer Agent
    role: software_developer
    model: gpt-4
    systemPrompt: "You are an expert software developer..."
    tools: [git, file_system, code_search]
    maxIterations: 10
    temperature: 0.7

workflows:
  - id: default
    name: Default Workflow
    trigger: manual
    steps:
      - id: analyze
        agentId: developer
        action: analyze_issue
        next: [implement]

LLM Providers

GSD-2 supports the following LLM providers and backends:

Provider	Type	Configuration	Base URL	Example Models
OpenAI	openai	OPENAI_API_KEY	(default)	gpt-4, gpt-4o, gpt-3.5-turbo
Gemini	gemini	GEMINI_API_KEY or LLM_PROVIDER=gemini	N/A (direct API)	gemini-2.5-pro-preview-05-06
Kimi	openai (compatible)	OPENAI_API_KEY + OPENAI_API_BASE_URL	https://api.kimi.com/coding/v1	k2p5, kimi-for-coding, kimi-k2.5
Ollama	openai (compatible)	OPENAI_API_KEY + OPENAI_API_BASE_URL	http://localhost:11434/v1	llama3.2, codellama, mistral
Anthropic	openai (compatible, via bridge)	OPENAI_API_KEY + OPENAI_API_BASE_URL	(bridge URL)	claude-3-opus, claude-3-sonnet
OpenAI-Compatible	openai (compatible)	OPENAI_API_KEY + OPENAI_API_BASE_URL	(your endpoint)	Any compatible model
Default	openai	OPENAI_API_KEY (no base URL, no explicit provider)	(OpenAI default)	gpt-4

How it works:

• The LLM_PROVIDER env var selects the provider type (openai or gemini). When unset, it auto-detects from available API keys.
• When OPENAI_API_BASE_URL is set, the OpenAI SDK client routes to that endpoint — enabling any OpenAI-compatible API (Kimi, Ollama, Anthropic via bridge, etc.).
• The LLM_MODEL env var overrides the default model (gpt-4 for OpenAI, gemini-2.5-pro-preview-05-06 for Gemini).
• Both the server (LLMService) and Docker worker (AgentExecutor) respect these environment variables.

Environment Variables

# Server
PORT=3001
NODE_ENV=development
DB_PATH=./data/gsd2.db

# LLM Provider
OPENAI_API_KEY=your_key_here
GEMINI_API_KEY=your_gemini_key_here  # Optional: for Gemini provider
LLM_PROVIDER=openai                  # 'openai' or 'gemini'
OPENAI_API_BASE_URL=                 # Optional: for OpenAI-compatible APIs
LLM_MODEL=gpt-4                      # Model to use

# APIs
GITHUB_TOKEN=your_token_here

# Worker
API_URL=http://localhost:3001
WORKER_TOKEN=secure_token

Docker Worker Lifecycle

1. Registration: Worker registers with API server
2. Heartbeat: Regular health checks every 30 seconds
3. Run Assignment: API assigns run to available worker
4. Repository Setup: Clone/pull repository
5. Issue Processing: Execute workflow for each issue
6. Attempt Tracking: Multiple attempts with metrics
7. Result Submission: Push branch, update run status
8. Cleanup: Container stops, results persisted

Development

Project Structure

/
├── app/                    # React frontend
│   ├── src/
│   │   ├── components/     # UI components
│   │   ├── pages/          # Page components
│   │   ├── hooks/          # Custom hooks
│   │   ├── store/          # Zustand store
│   │   ├── lib/            # API and WebSocket clients
│   │   └── types/          # TypeScript types
│   └── dist/               # Build output
├── server/                 # Express backend
│   ├── src/
│   │   ├── models/         # TypeORM entities
│   │   ├── services/       # Business logic
│   │   ├── routes/         # API routes
│   │   └── config/         # Database config
│   └── dist/               # Build output
├── docker-worker/          # Autonomous worker
│   ├── src/
│   │   ├── agents/         # Agent executor
│   │   ├── git/            # Git manager
│   │   └── utils/          # Utilities
│   └── Dockerfile
└── shared/                 # Shared types

Testing

The project uses Vitest for unit testing across the frontend and Docker worker packages.

Run Tests

# Frontend tests
cd app
npm test

# Docker worker tests
cd docker-worker
npm test

Test Coverage

Package	Test File	Tests	Description
app	src/lib/__tests__/utils.test.ts	5	cn() utility (clsx + twMerge)
app	src/store/__tests__/store.test.ts	10	Zustand store CRUD, sidebar, theme, notifications
app	src/lib/__tests__/api.test.ts	5	API client config, endpoint exports
app	src/lib/__tests__/websocket.test.ts	7	WebSocketClient subscribe, send, connect
app	src/types/__tests__/types.test.ts	13	Status type values, ForgeType
docker-worker	src/__tests__/logger.test.ts	7	Logger levels, formatting, filtering
docker-worker	src/__tests__/types.test.ts	5	WorkerConfig, RunPayload, WorkerStatus enum

Total: 52 tests across 7 test files

Watch Mode

cd app && npm run test:watch
cd docker-worker && npm run test:watch

License

MIT