# Fractals

> Recursive agentic task orchestrator that decomposes any high-level task into a self-similar tree of subtasks and executes each leaf in isolated git worktrees using an agent swarm.

Fractals is an open-source recursive task orchestrator built by TinyAGI, available on GitHub under the MIT License. It takes a high-level task description, recursively decomposes it into a tree of atomic subtasks, and then executes each leaf node in an isolated git worktree using Claude CLI or Codex CLI agents. The project is marked as experimental and is written primarily in TypeScript.

## What It Is

Fractals sits in the multi-agent orchestration category. Its core job is to bridge the gap between a vague, high-level goal and concrete, executable code-level work. Rather than asking a single agent to handle a complex task end-to-end, Fractals grows a "fractal tree" of subtasks — each composite node is broken down further until only atomic, directly executable leaves remain. Those leaves are then handed off to AI coding agents running in parallel, each in its own isolated git worktree to avoid conflicts.

## Architecture and Two-Phase Flow

The system is split into two distinct phases:

- **Plan phase**: The user enters a task and a max depth. An OpenAI model (gpt-5.2 per the source) classifies each node as atomic or composite. Composite nodes are recursively decomposed until all leaves are atomic and marked "ready."
- **Execute phase**: The user reviews the full plan tree, provides a workspace path (git-initialized automatically), and triggers batch execution. Each leaf task is run via `claude --dangerously-skip-permissions` in its own git worktree, with real-time status polling from the frontend.

The server runs on port 1618 — a deliberate reference to the golden ratio, the constant behind fractal geometry.

## Stack and Components

The project uses a Next.js frontend for task input, tree visualization, and status polling, backed by a Hono API server. Key internal modules include:

- `llm.ts` — OpenAI calls for classify and decompose with structured output
- `orchestrator.ts` — Recursive `plan()` that builds the tree without executing
- `executor.ts` — Claude CLI invocation per task in a git worktree
- `workspace.ts` — git init and worktree management
- `batch.ts` — Batch execution strategies (depth-first implemented; breadth-first and layer-sequential on the roadmap)

## Batch Execution and Roadmap

Because of rate limits, leaf tasks execute in batches rather than all at once. The currently implemented strategy is depth-first: all leaves under one branch complete before moving to the next, with tasks within a branch running concurrently. The roadmap includes breadth-first and layer-sequential strategies, as well as a backpropagation "merge agent" that would combine worktree branches bottom-up after execution, LLM-inferred task dependencies, persistent sessions, and SSE/WebSocket real-time updates.

## Current Status

The repository carries an "experimental" stability badge. According to the GitHub metadata, the project was created in early 2026 and last updated in May 2026, with 633 stars and 46 forks at the time of data collection. It is actively maintained under the TinyAGI organization, which also operates the tinyagicompany.com platform focused on AI-native company infrastructure.

## Features
- Recursive task decomposition into a self-similar subtask tree
- Atomic vs. composite task classification via LLM
- Isolated git worktree execution per leaf task
- Claude CLI and Codex CLI executor support
- Next.js frontend with real-time tree visualization
- Depth-first batch execution strategy
- Configurable max recursion depth
- Automatic git workspace initialization
- REST API for session, decompose, workspace, execute, and tree state
- OpenAI structured output for classify and decompose

## Integrations
OpenAI (gpt-5.2), Claude CLI, Codex CLI, Git, Next.js, Hono

## Platforms
WEB, CLI, API

## Pricing
Open Source

## Version
main

## Links
- Website: https://tinyagicompany.com
- Documentation: https://github.com/TinyAGI/fractals
- Repository: https://github.com/TinyAGI/fractals
- EveryDev.ai: https://www.everydev.ai/tools/fractals-tinyagi