fractal

Purpose

Fractal aims to accomplish complex tasks with hierarchical, recursively self-organizing agent loops. It organizes autonomous agent loops into a tree of git worktrees: each node iterates toward a goal in its own worktree and spawns child nodes when it encounters separable subtasks. In this way the task tree grows according to what the problem actually requires, rather than executing a pre-fixed plan.

Main capabilities

• Tree-shaped agent loops: the root (user) node, which has no worktree and no loop of its own, is the current branch; top-level nodes branch from it, and child nodes branch from their parent.
• Hard boundaries: each loop is constrained by upper limits on iteration count, depth, number of children, total number of descendants, cost, and time.
• Runtime metadata: all state (runs, iters, steps, costs, signals) is recorded in a local SQLite database and can be viewed and interacted with in real time through a terminal UI.
• Five agent backends: Claude Code (claude), Codex (codex), Grok Build (grok), OpenCode (opencode), Oh My Pi (omp), selected per node with --agent, and inherited by child nodes.
• OpenRouter routing: Claude and Codex can go through OpenRouter via --provider=openrouter, authenticating with the OPENROUTER_API_KEY from the shell that launched them; OpenCode and Oh My Pi connect natively through their own openrouter/<author>/<model> model IDs.
• Unattended loops: approval gates are disabled by default (Claude bypassPermissions, Codex danger-full-access, Grok --always-approve, opencode --auto, omp --yolo), and nodes can run any command their agent decides on.
• Operator control: the loop can be guided or stopped at any time.

How to use

Install from PyPI:

• pipx install plasma-fractal or uv tool install plasma-fractal. When using these two isolated installation methods, plasma-wiki must also be installed; a one-command equivalent is uv tool install plasma-fractal --with-executables-from plasma-wiki.
• A normal pip install will pull in plasma-wiki and put the wiki on PATH.

In the project root, use fractal open to open the dashboard (requires an initialized fractal); for a light-colored terminal, add --light.

To install the skill for agents: it can be done through the plugin marketplace (Claude Code and Codex); or install from the CLI by copying (or symlinking) the fractal and wiki skills to ~/.claude/skills and ~/.agents/skills (add --project for the current project only). After upgrading the package, rerun fractal install to refresh the copied skills (--link for symlink installation).

Use the /fractal skill to generate and manage agent nodes; you can also use the CLI directly, running fractal --help and fractal <command> --help to explore. The skill is invoked as /fractal [directive], accepts natural-language instructions, and the agent will interpret the instructions, print the NODE.md instructions and completion requirements that can be distilled from them, along with tables for each parameter (leaving blank any not mentioned in the instructions), then ask about anything that cannot be inferred, after which it guides refinement of the node definition, and once approved launches the node in a tmux session. If tmux cannot run, add --headless, and the node output is appended to headless.log; delegated child nodes use the parent node's backend, and a restart without flags reuses the backend the node used when it was last launched.

The parameters the skill can interpret include: name (node name, alphanumeric and underscores only, required), path, title, scope, base, meta, inherit, agent, provider, model, effort, max-iters, max-depth, max-children, max-descendants, timeout, iter-timeout, step-timeout, interval, sleep, wait, max-cost, max-iter-cost, max-step-cost, reserve-budget, sync, detached, local.

Local development installation: run install.sh in the package root directory; when there is no active environment, create and use a local .venv; when there is an active environment (such as pyenv), install editable within it. ./install.sh --help shows all options; you can also manually run uv sync --all-extras --group test --group lint --group type and uv run pre-commit install. Under an editable installation, fractal install --link will symlink the built-in skill. After installation, run tools with uv run --no-sync <command>, or first source .venv/bin/activate.

Run the test suite (with --doctest-modules enabled; integration tests create real git repositories and worktrees), as well as run the linter and formatter. For the contribution workflow, repository conventions, and release process, see CONTRIBUTING.md, AGENTS.md, RELEASING.md; PRs should be branched from the dev branch and submitted against dev, and main advances only at release time.

Use Cases

Suitable for scenarios where decomposable complex tasks are handed to multiple autonomous agents for parallel, hierarchical progression, and hard constraints such as cost, time, and depth are required, along with unified run metadata tracking. Because nodes run without approval prompts by default and can execute arbitrary commands, you should only start task nodes that you trust to run unsupervised; in other cases, prefer using a sandbox or a disposable host.

Limitations

• Each node's git worktree only isolates the branch it commits to; it does not isolate the filesystem, network, or other external environments.
• The unattended loop cannot stop to ask questions, approval gates are disabled by default, and nodes have your credentials and the machine's reachable scope.
• Cost limits are set independently per run: after a run whose budget has ended, node start --continue will be rejected without an explicit --max-cost.
• Some parameters (such as max-step-cost) are only warnings when they cannot be enforced.

License

Apache License 2.0, see LICENSE for details. Copyright © 2026 Plasma AI。