Fractals is a recursive task orchestrator for agent swarms, designed to break down high-level tasks into a self-similar tree of executable subtasks. It addresses the complexity of managing distributed agent workflows by automatically decomposing tasks, executing leaf nodes in isolated Git worktrees, and orchestrating the process. This offers engineers and power users a structured, automated approach to complex task execution and agent coordination.

How It Works

The system operates in two phases: PLAN and EXECUTE. During the PLAN phase, an LLM (e.g., OpenAI's gpt-5.2) classifies the input task and recursively decomposes it into a hierarchical tree structure. The EXECUTE phase initializes a Git repository, creates isolated worktrees for each leaf task, and runs them concurrently using the Claude CLI. Tasks are batched to manage API rate limits, with depth-first execution currently implemented. The architecture comprises a Next.js frontend for user interaction and visualization, and a Hono.js backend server managing orchestration logic.

Quick Start & Requirements

Installation requires a Node.js environment. After cloning the repository, install server dependencies with npm install, then navigate to the web directory to install frontend dependencies (cd web && npm install && cd ..). A valid OpenAI API key must be provided via an .env file (OPENAI_API_KEY=sk-...). Start the backend server using npm run server (defaults to port 1618) and the frontend development server with cd web && npm run dev (defaults to port 300