The Problem
Managing complex tasks with an AI swarm is a pain. You give ChatGPT some vague project spec, and it spits out a single, linear plan. Real work isn’t linear—there are dependencies, subtasks, and rabbit holes. Orchestrating recursive agent tasks manually is a nightmare, especially if you want each leaf to run in isolation and not step on each other's toes.
What This Does
fractals takes a high-level task, recursively breaks it down, and spins up a tree of subtasks. The backend is in src/—server.ts uses Hono for the API, and llm.ts handles OpenAI calls for classifying and decomposing tasks. The real magic is in orchestrator.ts, which builds out the recursive tree and manages batch strategies. Each leaf task runs in its own git worktree, handled by executor.ts and workspace.ts. The frontend (Next.js, living in web/) lets you enter tasks, review the generated tree (web/src/components/task-tree.tsx), and track execution status.
Batch execution isn’t just a buzzword; it’s necessary for AI rate limits. Depth-first is implemented, so you’ll see branch 1.x finish before 2.x. Breadth-first and layer-sequential are on the roadmap, but the code for that isn’t here yet.
Real-World Use
Say you want to "Build a Python web scraper and deploy it." You punch that into the UI. The server (via llm.ts) classifies and recursively breaks it down—maybe into “Write scraper,” “Test scraper,” “Create Dockerfile,” “Deploy to Heroku.” You review the tree, pick your workspace (it auto-inits git in ~/fractals/<task-slug>), and hit execute. Each leaf gets its own isolated git worktree, and Claude CLI (or whatever) runs the actual agent tasks. The frontend polls for status, so you see progress in real time.
The Bottom Line
fractals is cool if you’re tired of linear AI assistants and want recursive planning with real isolation. It’s overkill for small tasks, but if you’re wrangling big projects or want agent swarms that don’t trash your main workspace, it works. The UI is basic, and you’ll need to babysit workspace paths. If you’re comfortable with git and CLI tools, it’s worth a try. Otherwise, keep your workflow simple.