plasma-ai/fractal: hierarchical agent loops that spawn their own subtask trees
Hierarchical agent loops with recursive self-organization.
At a glance
- What is it?
- fractal turns an autonomous coding agent into a tree of git worktrees, each node iterating toward a goal and branching children for separable subtasks. The pitch is self-organization; the catch is that every node runs without permission prompts.
- Who is it for?
- Adopt fractal if you already run unattended coding agents on a disposable or sandboxed host and want the tree structure, the hard caps and the SQLite run ledger. Do not adopt it if your agents need approval prompts, if you cannot give a node a task you would trust to run unsupervised, or if you need a stable released API: there are no releases retrieved and the CLI surface is still described only through --help.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem fractal solves, and who it is aimed at
A single agent loop with a fixed plan fails in a predictable way: the plan was written before the agent knew anything about the repository. fractal inverts that. The README describes a tree in which 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. The root is your current branch. It has no worktree and no loop of its own. Top-level nodes branch from it, and child nodes branch from their parent, which means the branch topology mirrors the task decomposition.
The audience is narrow and specific. You need to be comfortable with tmux, git worktrees, and handing a coding agent a task with no human in the loop. 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. If you are looking for a chat wrapper around one model, this is the wrong shape entirely.
How the tree, the caps and the SQLite ledger fit together
Each node is an agent loop running inside a tmux session. The README states that all state (runs, iters, steps, costs, signals) is tracked in a local SQLite database, and that run metadata including cost lands there. That database is the single place the tree's behaviour is observable, and the terminal UI reads it live.
Bounding is explicit rather than emergent. Hard caps on iterations, depth, children, cost and time keep each loop from running away, and an operator can steer or stop it at any point. Those caps are the design's answer to the obvious failure mode of recursive spawning: a node that keeps deciding a subtask is separable. Because the caps are per-loop and the tree is recursive, the effective budget is a product rather than a sum, which is worth checking against the cost column before you widen any limit.
Isolation is narrower than it sounds. The per-node git worktree isolates the branch a node commits to. The README is explicit that it does not isolate the filesystem, the network, or anything else outside the branch. Two nodes working in the same repository still share a machine, credentials and network reach.
Installing plasma-fractal and launching a first node
The package is on PyPI as plasma-fractal and requires Python >=3.12,<3.15. A plain pip install pulls plasma-wiki and puts wiki on your PATH.
pip install plasma-fractalIf you prefer an isolated environment, the README recommends pipx install or uv tool install, but warns that neither brings plasma-wiki with it. The one-command form is:
uv tool install plasma-fractal --with-executables-from plasma-wikiAfter installing, the CLI is available as fractal (the entry point is fractal.cli.main:cli). Run fractal --help and fractal <command> --help to see the surface, since the README points there rather than listing every subcommand.
The intended first use is through the agent skill rather than the CLI. Install it from the plugin marketplace for Claude Code or Codex:
/plugin marketplace add plasma-ai/plugins
/plugin install fractal@plasmaAlternatively, fractal install copies or symlinks the fractal and wiki skills into ~/.claude/skills and ~/.agents/skills; add --link for symlinks and --project to limit the install to the current project. You then invoke /fractal [directive] in plain language. The skill interprets the directive, prints any suggested NODE.md instructions and completion requirement it could distill, shows a table of every parameter with the ones the directive did not cover left empty, asks for what it could not infer, and launches the node in a tmux session once you approve. Node names accept letters, digits and underscores only, so a hyphen in a name will be rejected. To watch the tree, run fractal open from your project root (it requires an initialized fractal), and pass --light if your terminal uses a light color scheme.
The permission model is the limitation, not a footnote
The README carries a warning, and it is the most consequential thing in the document. Nodes run their agent without permission prompts by default, because unattended loops cannot stop to ask. Every seeded agent config disables the approval gate: Claude uses bypassPermissions, Codex danger-full-access, Grok --always-approve, opencode --auto, and omp --yolo. A node can therefore run any command its agent decides to run, with your credentials and your machine's reach.
That is not a bug to be patched around; it follows from the premise. A loop that spawns children and iterates without a human present cannot also wait for a human. The README's own guidance is to launch only nodes whose task you would trust to run unsupervised, and to prefer a sandboxed or otherwise disposable host for anything else.
The second limitation is structural. Because children inherit the agent config and can inherit steps, scripts, skills and config surfaces from the parent, a bad seed propagates down the tree. The inherit parameter takes steps, scripts, skills, config or all, and agent config always inherits whether you ask for it or not. There is no documented rollback for a subtree that has already committed to its own branches, and the README does not describe one.
Where fractal sits next to a plain agent loop or a workflow engine
The nearest alternative is running one agent loop in one worktree and decomposing the task yourself. That approach keeps a single cost line, a single branch, and one place to intervene. Its difference is not a feature gap; it is a different decomposition model. You decide the subtasks up front, and the agent never decides that a piece of work is separable. fractal trades that predictability for the tree growing to fit the problem.
The other alternative is a static workflow engine, where you declare the DAG of steps and each step runs a prompt. Those give you a reviewable graph before anything executes, which matters when the plan is the thing under review. fractal's graph does not exist until the run creates it, and the caps are what stand in for the missing pre-flight review. If your task genuinely needs a plan a human signs off on, a declared DAG is the better fit, and fractal's self-organization is a liability rather than a feature.
Maintenance, packaging and licence implications
The last push to main was on 2026-09-17, and the repository is not archived. There are no releases retrieved, so the version you get from PyPI is the only versioning signal available: pyproject.toml declares 1.2.0. Treat the CLI as moving, because the README routes you to fractal --help rather than documenting the subcommands inline.
Upgrades have a manual step. The README says that after upgrading the package you must re-run fractal install to refresh the copied skills, and to pass --link if you installed them as symlinks. Skip that and the skill your agent loads will be the old one. The runtime dependencies are pinned to major ranges (plasma-wiki >=1,<2, rich >=15,<16, textual >=8,<9, typer >=0.24,<1), so a minor upgrade of textual or typer can land without a fractal release.
The licence is Apache-2.0, declared in pyproject.toml with license-files = ["LICENSE"]. That is a permissive licence with an explicit patent grant and a requirement to preserve notices. It says nothing about the agents fractal drives: Claude Code, Codex, Grok Build, OpenCode and Oh My Pi each carry their own terms, and routing Claude or Codex through OpenRouter via --provider=openrouter uses an OPENROUTER_API_KEY from the launching shell. Check those terms separately; the fractal licence does not cover them.
Editorial conclusion
Adopt fractal if you already run unattended coding agents on a disposable or sandboxed host and want the tree structure, the hard caps and the SQLite run ledger. Do not adopt it if your agents need approval prompts, if you cannot give a node a task you would trust to run unsupervised, or if you need a stable released API: there are no releases retrieved and the CLI surface is still described only through --help. Verify first that a single node behaves on your machine, that the caps you set actually stop the loop, and that plasma-wiki is on PATH if you installed with pipx or uv tool install.
Frequently asked questions
What is fractal in simple terms?
In this project, a fractal is a tree of git worktrees, each running an autonomous agent loop. A node iterates toward a goal in its own worktree and spawns child nodes for separable subtasks, so the tree grows to fit the problem.
How does a fractal work?
The root is your current branch and has no worktree or loop of its own. Top-level nodes branch from it 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.
How do I install plasma-fractal?
Install the plasma-fractal package from PyPI with pip install plasma-fractal, or use pipx install or uv tool install for an isolated environment. With pipx or uv tool install you must also install plasma-wiki, or use uv tool install plasma-fractal --with-executables-from plasma-wiki.
Which agent backends does fractal support?
Five: Claude Code (claude), Codex (codex), Grok Build (grok), OpenCode (opencode), and Oh My Pi (omp). The backend is selected per node with --agent and children inherit it.
Do fractal nodes ask for permission before running commands?
No. The README states that nodes run their agent without permission prompts by default, and that every seeded agent config disables the approval gate. The per-node git worktree isolates the branch a node commits to, not the filesystem or the network.
Community notes