plasma-ai/fractal

fractal – Hierarchical autonomous‑agent loops

What it is

• A Python library and CLI that lets you run recursive autonomous agents as a tree of Git worktrees. Each node in the tree is an independent agent loop that can spawn child nodes for sub‑tasks, forming a fractal structure that grows to match the problem size.
• All runs are recorded in a local SQLite database and can be inspected or controlled through a terminal‑based UI (TUI).

How it works

1. Root node – your current Git branch acts as the top‑level “user” node (it does not have its own worktree).
2. Spawning – you issue a plain‑language directive via the /fractal skill (or the fractal CLI). The agent parses the directive, asks for any missing parameters, and then creates a new Git worktree for the child node.
3. Iteration – each node runs an autonomous loop inside a tmux session, calling one of the supported LLM back‑ends (Claude, Codex, Grok, OpenCode, Oh My Pi). The loop can iterate, commit code, run commands, and spawn further children.
4. Bounding – caps on iterations, depth, number of children, time, and cost keep every loop bounded. Budgets are enforced per‑run and per‑step, with optional reservation for cleanup.
5. Tracking – every iteration, step, cost, and signal is stored in a single SQLite file. The TUI dashboard visualises the tree, shows live metrics, and lets you pause/stop nodes.

Key features

• Recursive self‑organization – nodes can create further nodes, letting the system adapt its structure to the problem.
• Multiple LLM back‑ends – Claude, Codex, Grok, OpenCode, and Oh My Pi, with optional routing through OpenRouter.
• Fine‑grained control – per‑node parameters for max‑iters, max‑depth, timeouts, cost ceilings, scopes, and more.
• Git‑centric workflow – each node works in its own Git worktree, so commits are isolated to a branch that can be pushed or kept local.
• Terminal UI – a live dashboard (fractal open) shows the tree, costs, and progress.
• Skill integration – a /fractal skill can be installed into Claude Code or Codex agents, enabling natural‑language spawning of nodes.
• Safety warnings – nodes run without permission prompts by default; the README stresses launching only trusted tasks and preferably on disposable hosts.

Installation

# From PyPI (the package is named "plasma-fractal" but also provides a "fractal" entry point)
pip install plasma-fractal   # or: pip install fractal

# For isolated installs (pipx, uv) also install the companion "plasma-wiki" package
pipx install plasma-fractal && pipx install plasma-wiki
# or with uv:
uv tool install plasma-fractal --with-executables-from plasma-wiki

After installing, run fractal open from a project root that has been initialized with fractal init (the README assumes an initialized fractal).

Typical workflow

# Open the dashboard (light theme optional)
fractal open --light

# From the TUI or via the skill, issue a directive, e.g.:
/fractal spawn name=docgen path=./docs title="Generate API docs" agent=claude max-iters=5

# The system will:
#   • Parse the directive, ask for missing fields
#   • Create a new git worktree under ./docs
#   • Start a tmux session that runs the Claude agent loop
#   • Record each iteration in the SQLite DB
#   • Show progress in the dashboard

You can stop, pause, or adjust a node with commands like fractal node stop <name> or by interacting with the UI.

Safety & limitations

• Nodes run without permission prompts, meaning the LLM can execute any command on the host with the launching user’s credentials. The README warns to use sandboxed or disposable machines for untrusted tasks.
• Cost caps are enforced, but only in USD per run; you must set appropriate max‑cost values to avoid runaway API charges.
• The system relies on external LLM providers; network access and API keys are required (e.g., OPENROUTER_API_KEY).

Documentation & community

• Official docs: https://docs.plasma.ai/fractal
• PyPI page: https://pypi.org/project/plasma-fractal/
• Source code: https://github.com/plasma-ai/fractal (Apache‑2.0 license)

Who might use it

• Developers who want an automated, self‑organizing workflow for large code‑base refactors, documentation generation, or multi‑step AI‑driven tasks.
• Researchers exploring hierarchical AI agent architectures.
• Teams that already use Claude, Codex, or other supported LLMs and want tighter integration with Git.

---

All details above are taken directly from the repository’s README; no additional features have been inferred.