Show HN: Fractal – recursive agent loops for complex, multi-step work

Plasma AI released Fractal, an open-source tool that uses recursive agent loops organized in a tree of git worktrees to autonomously decompose and complete complex, multi-step tasks. Each node iterates toward a goal, spawns child nodes for separable subtasks, and is bounded by hard caps on iterations, depth, children, cost, and time, with all run metadata stored in a local SQLite database accessible via a terminal UI. The tool supports five agent backends—Claude Code, Codex, Grok Build, OpenCode, and Oh My Pi—and is available on PyPI as the 'plasma-fractal' package.

Hierarchical agent loops with recursive self-organization. In a fractal, autonomous agent loops arrange themselves into a tree: a node iterates toward a goal in its own git worktree and spawns child nodes for separable subtasks, so the tree grows to fit the problem rather than a fixed plan. Hard caps iterations, depth, children, cost, time keep each loop bounded, and an operator can steer or stop it at any point. Run metadata including cost lands in one local SQLite database, which can be interacted with live in a terminal UI. Source : https://github.com/plasma-ai/fractal https://github.com/plasma-ai/fractal Package : https://pypi.org/project/plasma-fractal/ https://pypi.org/project/plasma-fractal/ Documentation : https://docs.plasma.ai/fractal https://docs.plasma.ai/fractal Install the fractal package from PyPI: pip install plasma-fractal or pip install fractal Use pipx install or uv tool install to install the package in an isolated environment. If you use one of these two methods, you must also install plasma-wiki a plain pip install pulls plasma-wiki and puts wiki on your PATH , but this is not the case when using pipx install or uv tool install . uv tool install plasma-fractal --with-executables-from plasma-wiki does the same in one command. Open the dashboard from your project root with fractal open requires an initialized fractal . Pass --light if your terminal uses a light color scheme. Install the skill for your agent via the plugin marketplace Claude Code and Codex : Claude Code /plugin marketplace add plasma-ai/plugins /plugin install fractal@plasma Codex codex plugin marketplace add plasma-ai/plugins codex plugin add fractal@plasma Another install route is from the CLI, which copies or symlinks the fractal and wiki skills into ~/.claude/skills and ~/.agents/skills add --project for the current project only : fractal install --link After upgrading the package, re-run fractal install to refresh the copied skills pass --link for symlinked install . A fractal is a tree of git worktrees, each running an autonomous agent loop. The root node branches from your working tree, and child nodes branch from their parent. Agents iterate in tmux sessions, and all state runs, iters, steps, costs, signals is tracked in a local SQLite database. Five agent backends are supported — Claude Code claude , Codex codex , Grok Build grok , OpenCode opencode , and Oh My Pi omp — selected per node with --agent children inherit it . Claude and Codex can additionally route through OpenRouter with --provider=openrouter , which authenticates via OPENROUTER API KEY from the launching shell; OpenCode and Oh My Pi reach OpenRouter natively through their own openrouter/<author /<model model ids. Use the /fractal skill to spawn and manage agent nodes. The fractal CLI is also available directly — run fractal --help and fractal <command --help to explore. The skill is invoked as /fractal directive and takes plain-language instructions. The agent interprets the directive and prints any suggested NODE.md instructions and completion requirement it can distill from the directive, plus a table of every parameter empty where the directive said nothing , then asks for anything it could not infer. From there it walks you through refining the node's definition and, once you approve, launches the node in a tmux session. Parameters the skill interprets from the directive: : node name required; letters, digits, and name only — no - : project root, repo root or monorepo sub-project default: path . : human-readable display name default: de-slugged node name title : restrict commits to subdirectories within the worktree comma-separated, e.g. scope parent/child,tests : branch to start from default: current branch base : target node branch for meta-configuration meta : seed surfaces from the parent node instead of the package seed comma-separated: inherit steps , scripts , skills , config , or all ; agent config always inherits. A top-level spawn's parent is the user node, which carries no steps, scripts, or skills — the parameter is for configured nodes spawning children: agent command; inherits the user node's default when omitted agent : provider route for the agent e.g. provider openrouter ; inherits the user node's default when omitted: model override; when omitted, the agent uses its own default model model : reasoning-effort override; when omitted, each agent seed's own pinned level applies, not the vendor default effort : per-run iteration cap max-iters : maximum child node nesting depth max-depth : maximum direct child nodes max-children : maximum total descendant nodes max-descendants : per-run time limit e.g. timeout 30m , 1.5h : per-iteration time limit e.g. iter-timeout 30m , 1.5h : per-step time limit e.g. step-timeout 30s , 10m ; caps each step: fixed iteration schedule e.g. interval 1h : delay between iterations e.g. sleep 10s : sleep between approval-wait sync invocations default: wait 1m : cost ceiling in USD per run — runs are isolated, so each launch arms the cap anew; after a budget-ended run, max-cost node start --continue refuses without an explicit --max-cost : per-iteration cost ceiling in USD max-iter-cost : per-step cost ceiling in USD warn-only when unenforceable max-step-cost : budget reserved for cleanup; USD or N% of reserve-budget max-cost default: 10% : enable default or disable radio sync before each step sync : run each step as a separate agent session default: one continuous session detached : skip pushing to remote after each commit local Run install.sh in the package root. With no environment active it creates and uses a local .venv ; with one active e.g. pyenv it installs into that environment editable , without recreating it: ./install.sh --all-extras --groups=test,lint,type Run ./install.sh --help for all options. Alternatively, run uv sync --all-extras --group test --group lint --group type and uv run pre-commit install to set up the environment manually. Installing a dependency as editable e.g. a sibling package is left to the caller: uv pip install --editable <path . With an editable install, fractal install --link symlinks the bundled skill into the agent skill directories instead of copying it, so skill edits apply without re-running the install. Once installed, run tools with uv run --no-sync <command , or activate the environment first source .venv/bin/activate . Run the test suite: pytest . The suite runs with --doctest-modules enabled, and the integration tests create real git repositories and worktrees. Run linters and formatters: pre-commit run --all-files The contribution workflow, repository conventions, and release process version sources, tagging, CI guard are documented in: - Contribution workflow organization-wide : CONTRIBUTING.md https://github.com/plasma-ai/.github/blob/main/CONTRIBUTING.md - Repository conventions: AGENTS.md https://github.com/plasma-ai/fractal/blob/main/AGENTS.md - Release process organization-wide : RELEASING.md https://github.com/plasma-ai/.github/blob/main/RELEASING.md Licensed under the Apache License 2.0 — see LICENSE https://github.com/plasma-ai/fractal/blob/main/LICENSE . Copyright © 2026 Plasma AI