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
Package: https://pypi.org/project/plasma-fractal/
Documentation: 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):
/plugin marketplace add plasma-ai/plugins
/plugin install fractal@plasma
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, andname
_
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-configurationmeta
: seed surfaces from the parent node instead of the package seed (comma-separated:inherit
steps
,scripts
,skills
,config
, orall
); 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 omittedagent
: 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 modelmodel
: reasoning-effort override; when omitted, each agent seed's own pinned level applies, not the vendor defaulteffort
: per-run iteration capmax-iters
: maximum child node nesting depthmax-depth
: maximum direct child nodesmax-children
: maximum total descendant nodesmax-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 USDmax-iter-cost
: per-step cost ceiling in USD (warn-only when unenforceable)max-step-cost
: budget reserved for cleanup; USD or N% ofreserve-budget
max-cost
(default: 10%): enable (default) or disable radio sync before each stepsync
: run each step as a separate agent session (default: one continuous session)detached
: skip pushing to remote after each commitlocal
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 - Repository conventions: AGENTS.md - Release process (organization-wide): RELEASING.md
Licensed under the Apache License 2.0 — see LICENSE.
Copyright © 2026 Plasma AI