SDD (Spec-Driven Development) — a cloud and web-based AI task management and agent orchestration platform powered by LLMs

Overview

MagesticAI is a browser-based platform for managing AI-powered coding tasks through coordinated autonomous agents. It provides a modern web interface for task creation, execution monitoring, terminal access, and code review - all accessible from any browser.

Key Features

• Kanban Task Board - Visual task management with drag-and-drop
• Multi-Agent Orchestration - Planner, Coder, and QA agents work together
• Real-time Terminal - Full PTY terminal access in browser
• Monaco Code Editor - VS Code-like editing experience
• Git Worktree Isolation - Safe, isolated builds per task
• AI-Powered QA - Automated code review and validation
• Multi-Provider Support - Claude, Codex, Gemini, and any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, OpenRouter, Together, Groq, LocalAI…) with native agentic tool calling (Read, Write, Edit, Bash, Glob, Grep) — no API fallback needed
• Graphiti Memory - Cross-session learning and knowledge retention
• Multi-Project Support - Manage multiple repositories
• Internationalization - English, French, Portuguese (Brazil)

Demo Video

A quick walkthrough of the Kanban board, task creation flow, and agent execution.

Screenshots

View	Preview
End-to-end architecture
Kanban task board
Task creation wizard
Built-in PTY terminal
Monaco code editor
Settings & onboarding

Supported Platforms

If you successfully run MagesticAI on a platform marked untested, open a PR adding your config to this table — happy to mark it ✅.

How does it compare?

MagesticAI sits next to two open-source projects with overlapping goals but very different shapes:

The short version: Spec Kit is great for authoring specs you'll execute with an existing agent. Compozy is great if you want a terminal-first multi-agent runner driving external agents. MagesticAI is the one to pick if you want the full spec → plan → code → QA loop in one self-hosted browser app, with first-class support for local and OpenAI-compatible LLMs.

Quick Start

Prerequisites

• Node.js 24+ and npm 10+
• Python 3.12+
• Git
• Claude Code OAuth Token (run claude setup-token)

Installation

# 1. Clone the repository
git clone https://github.com/dataseeek/MagesticAI.git
cd MagesticAI

# 2. Install all dependencies
npm run install:all

# 3. Configure environment
cp apps/backend/.env.example apps/backend/.env
cp apps/web-server/.env.example apps/web-server/.env
# Edit .env files with your CLAUDE_CODE_OAUTH_TOKEN

Running the Application

Terminal 1 - Backend Server:

cd apps/web-server
source .venv/bin/activate
python -m server.main
# Server runs on http://localhost:3101
# API token printed to console and saved to ~/.magestic-ai/.token

Terminal 2 - Frontend Dev Server:

cd apps/frontend-web
npm run dev
# UI available at http://localhost:3100

Docker Deployment

MagesticAI includes a Dockerfile and docker-compose.yml for containerized deployment:

# Build and start (clean)
docker compose down -v && docker compose build && docker compose up -d

# Start without rebuilding
docker compose up -d

# Retrieve the auto-generated API token
docker exec magesticai cat /home/magesticai/.magestic-ai/.token

Access the web UI at http://YOUR_HOST:3101 after the container starts.

See ContainerAPP.md for detailed Docker deployment instructions.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                   MagesticAI                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   Browser (React 19 + Vite)           Port 3100                 │
│   ├── Kanban Board                                               │
│   ├── Terminal Grid (xterm.js)                                   │
│   ├── Code Editor (Monaco)                                       │
│   ├── Task Detail Modal                                          │
│   └── Real-time WebSocket Updates                                │
│                                                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   Web Server (FastAPI)                Port 3101                 │
│   ├── REST API (/api/*)                                          │
│   ├── WebSocket Endpoints (/ws/*)                                │
│   ├── PTY Session Management                                     │
│   ├── Agent Execution Service                                    │
│   └── File Operations                                            │
│                                                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   Backend Agents (Python)                                        │
│   ├── Claude Agent SDK Integration                               │
│   ├── Multi-Provider Engine (Claude/Codex/Gemini/OpenAI-compat)  │
│   ├── Local LLM Tool Calling (Read/Write/Edit/Bash/Glob/Grep)    │
│   ├── Planner Agent (creates implementation plans)               │
│   ├── Coder Agent (implements subtasks)                          │
│   ├── QA Reviewer (validates code)                               │
│   ├── QA Fixer (resolves issues)                                 │
│   └── Graphiti Memory (LadybugDB)                                │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Tech Stack

Frontend (apps/frontend-web/)

Backend Web Server (apps/web-server/)

Backend Agents (apps/backend/)

Project Structure

MagesticAI/
├── apps/
│   ├── frontend-web/        # React web frontend (Vite)
│   │   ├── src/
│   │   │   ├── components/  # 57+ React components
│   │   │   ├── stores/      # 14 Zustand stores
│   │   │   ├── hooks/       # Custom React hooks
│   │   │   ├── lib/         # API client, WebSocket
│   │   │   └── shared/      # Types, i18n, constants
│   │   └── package.json
│   │
│   ├── web-server/          # FastAPI backend
│   │   └── server/
│   │       ├── routes/      # REST API endpoints
│   │       ├── websockets/  # WebSocket handlers
│   │       ├── services/    # Agent execution service
│   │       └── pty/         # Terminal management
│   │
│   ├── backend/             # Python agent system
│   │   ├── agents/          # Planner, Coder agents
│   │   ├── providers/       # Multi-LLM adapters (Claude, Codex, Gemini, OpenAI-compatible inc. Ollama)
│   │   ├── tools/           # Reusable tool executor (Read, Write, Edit, Bash, Glob, Grep)
│   │   ├── qa/              # QA Reviewer, Fixer
│   │   ├── spec/            # Spec creation pipeline
│   │   ├── security/        # Command validation & path boundary
│   │   ├── integrations/    # Graphiti, Linear, GitHub
│   │   └── prompts/         # Agent system prompts
│   │
├── guides/                  # Extended documentation
├── tests/                   # Test suite
├── scripts/                 # Build scripts
├── Dockerfile               # Container image definition
├── docker-compose.yml       # Container orchestration
├── CHANGELOG.md             # Version history
├── RELEASE.md               # Release process guide
├── AGENTS.md                # AI agent instructions
├── GEMINI.md                # Gemini AI instructions
├── ContainerAPP.md          # Docker deployment guide
└── package.json             # Root package

Views & Features

Task Lifecycle

1. CREATE     →  TaskCreationWizard generates spec
2. PLAN       →  Planner Agent creates subtask plan
3. CODE       →  Coder Agent implements in isolated worktree
4. QA REVIEW  →  QA Agent validates against acceptance criteria
5. FIX        →  QA Fixer resolves any issues (loops back to QA)
6. MERGE      →  Human reviews and merges to main branch

Configuration

Environment Variables

Backend (apps/backend/.env):

CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token
GRAPHITI_ENABLED=true
# Optional: LINEAR_API_KEY, GITHUB_TOKEN

Web Server (apps/web-server/.env):

APP_HOST=0.0.0.0
APP_PORT=3101
APP_DEBUG=true
# APP_API_TOKEN=xxx  # Auto-generated if not set

Frontend (apps/frontend-web/.env):

VITE_API_BASE_URL=/api
VITE_WS_BASE_URL=ws://localhost:3101

OpenAI-Compatible Endpoints

MagesticAI can talk to any service that implements the OpenAI POST /v1/chat/completions protocol: Ollama (at http://localhost:11434/v1), LM Studio, vLLM, OpenRouter, Together AI, Groq, LocalAI, and OpenAI itself.

1. Add the endpoint in the UI Open Settings → LLM Accounts → "OpenAI-Compatible Endpoints" → "Add endpoint". Fill in:

• Label (e.g. LM Studio local, Ollama local)
• Base URL (e.g. http://localhost:1234 for LM Studio, http://localhost:11434/v1 for Ollama — Ollama needs the /v1 suffix; LM Studio / vLLM do not)
• API key (leave blank for local servers like LM Studio / Ollama that don't need one)
• Default model (e.g. qwen2.5-coder-32b-instruct, qwen2.5-coder:32b for Ollama)

Use the "Test" button to confirm the server is reachable.

2. Select it for a task Prefix the model name with openai: or openai-compatible::

The backend reads base_url and api_key directly from the llm_endpoints table in ~/.magestic-ai/data.db — same row the Settings UI writes when you click Create.

For power users without the UI, the env vars OPENAI_COMPATIBLE_BASE_URL and OPENAI_COMPATIBLE_API_KEY (or OPENAI_API_KEY) act as a fallback when no DB row exists.

Model size matters. Smaller local models (under ~30B parameters) can call tools and write files, but they sometimes drift from the exact JSON schemas MagesticAI expects (spec.md, implementation_plan.json, qa_report.md, etc.). When that happens the build pipeline has a built-in retry loop that feeds the validation error back to the model and asks it to fix the file — but small models don't always recover, and a corrupted spec can fail the whole task. For reliable end-to-end runs, prefer one of:

• Larger local models: qwen2.5-coder-32b-instruct, llama-3.3-70b-instruct, deepseek-coder-v2:33b
• Hosted endpoints via OpenRouter / Together / Groq: any GPT-4-class or Claude-class model
• Test small models on a throwaway task first before committing to a multi-hour build

Tool-call protocol support also varies — make sure your chosen model is one LM Studio / vLLM advertises as supporting OpenAI tool calling.

API Endpoints

REST API (/api/)

WebSocket Endpoints (/ws/)

Documentation

• CLAUDE.md - AI assistant instructions and architecture reference
• AGENTS.md - Agent configuration for AI coding tools
• GEMINI.md - Gemini AI assistant instructions
• CHANGELOG.md - Version history and release notes
• RELEASE.md - Release process documentation
• ContainerAPP.md - Docker deployment guide
• guides/ - Extended technical documentation

Scripts

# Development
npm run dev              # Start web frontend (dev mode)

# Installation
npm run install:all      # Install all dependencies
npm run install:backend  # Backend only
npm run install:frontend # Frontend only

# Testing
npm run test             # Run frontend tests
npm run test:backend     # Run backend tests

# Production
npm run build            # Build frontend for production

Troubleshooting

Contributing

We welcome contributions! To get started:

1. Fork the repository
2. Create a feature branch from develop: git checkout -b fix/my-fix develop
3. Make your changes and commit with sign-off: git commit -s -m "fix: description"
4. Push to your branch: git push origin fix/my-fix
5. Create a PR targeting develop: gh pr create --base develop

See RELEASE.md for the full release and versioning process.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

See LICENSE for the full license text and NOTICE for copyright and upstream attribution (MagesticAI is a derivative work of Aperant by @AndyMik90 and inherits its AGPL-3.0 license).

Credits

MagesticAI is a fork of Aperant (formerly Auto Claude Desktop) by @AndyMik90. We thank the original authors for the foundational work.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Made with AI by DataSeek Team

Star History