The Problem

Teams that need to break a vague, high‑level objective into concrete, executable steps often build ad‑hoc scripts or manual checklists. Coordination, state tracking and reproducible execution become fragile, especially when many small tasks must run in isolated environments (e.g., separate git worktrees).

What This Does

fractals implements a recursive task orchestrator that accepts a top‑level description, calls an LLM to classify and decompose it, builds a self‑similar tree of subtasks, and executes leaf tasks in isolated git worktrees. The core lives in src/ (the Hono HTTP API) while the UI lives in web/ (a Next.js front‑end). Key files include:

  • src/index.ts – re‑exports the public API.
  • src/server.ts – creates the Hono server, registers routes, and enables CORS.
  • src/orchestrator.ts – plan, createTask, buildTree, leaves.
  • src/llm.ts – classify and decompose wrappers around OpenAI.
  • src/executor.ts – runCommand, invokeClaude, invokeCodex, buildPrompt.
  • src/workspace.ts – file‑system helpers (resolvePath, run, initWorkspace, createWorktree, removeWorktree).
  • web/src/lib/api.ts – client‑side API (getSession, decompose, initWorkspace, startExecution, getTree).

The UI renders the task tree (web/src/components/task-tree.tsx) and polls the server for execution status.

How It Is Wired

  1. Entry point – src/index.ts exports the server created in src/server.ts. When the process starts (npm start or equivalent), src/server.ts runs new Hono() and attaches routes.
  2. Request flow – A POST to /decompose (handled in web/src/lib/api.ts) calls src/llm.ts::classify → src/llm.ts::decompose. Both forward the prompt to OpenAI and return a structured task description.
  3. Planning – src/orchestrator.ts::plan receives the decomposed task, uses createTask (adds TaskKind and TaskStatus from src/types.ts) and recursively builds the tree via buildTree. leaves extracts leaf nodes. This module has the highest inbound fan‑in (3 modules) and low instability (0.4), making it a stable hub.
  4. Batch creation – src/batch.ts::createBatches (called from the orchestrator) orders leaf tasks using batchDepthFirst.
  5. Execution – For each leaf, src/executor.ts::runCommand spawns the appropriate CLI (Claude or Codex) with a prompt built by src/executor.ts::buildPrompt. invokeClaude / invokeCodex are thin wrappers that ultimately call the external binary.
  6. Workspace handling – src/workspace.ts prepares a git worktree per leaf (initWorkspace, createWorktree, removeWorktree). It is the only module that reads/writes the filesystem.
  7. Client polling – The front‑end (web/src/app/page.tsx) calls api.getTree and repeatedly fetches task status, rendering updates via the UI components.

The internal call graph shows cn (utility in web/src/lib/utils.ts) referenced from seven places, making it a cross‑cutting helper. No circular imports were detected, so the dependency graph is straightforward.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/fractals.git
cd fractals

# Install root dependencies (npm inferred from package.json)
npm ci

# Install front‑end dependencies
cd web && npm ci && cd ..

# Start the API server (script defined in package.json, e.g., "npm start")
npm run start   # runs src/server.ts on port 1618

# In a second terminal, start the Next.js UI
cd web && npm run dev   # defaults to http://localhost:3000

Configuration – The server expects no external config files; however, OpenAI and Claude credentials must be provided via environment variables used inside src/llm.ts (e.g., OPENAI_API_KEY). The repository does not include a .env.example, so users must create these variables before invoking the API.

Real‑World Use

A product team can point the UI at a new feature request: “Add multi‑language support for the dashboard”. The LLM decomposes the request into subtasks (e.g., “Translate UI strings”, “Add locale switcher”). Each leaf runs in its own worktree, guaranteeing that changes are isolated and can be reviewed or reverted independently before merging into the main codebase.

Code Health & Issues

  • High – No test suite – 26 source files, zero test files.
  • High – No CI workflow – No .github/ or other CI config.
  • High – Wildcard CORS – src/server.ts uses cors() without origin restriction while credentials are allowed.
  • Medium – Duplicated code blocks – 6‑line repeats across src/executor.ts, src/workspace.ts, src/types.ts, web/src/lib/api.ts.
  • Medium – Enable Dependabot – Two lockfiles present, but no bot configuration.
  • Low – Missing repo conventions – No .editorconfig, .gitattributes, or formatter config.

The Bottom Line

fractals provides a clear, modular pipeline for LLM‑driven task decomposition and isolated execution, with a usable UI and a lightweight Hono API. The codebase is small and well‑structured but lacks automated testing, CI, and secure CORS handling, which are essential for production adoption. It is suitable for experimental or internal tooling where rapid iteration outweighs the current gaps in quality‑gate processes.