fractal README

The project's README from github.com/plasma-ai/fractal. As one markdown file: README.md.

fractal

license build docs lint tests codecov pre-commit

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.

fractal TUI dashboard

[!WARNING] Nodes run their agent without permission prompts by default. Unattended loops cannot stop to ask, so every seeded agent config disables the approval gate — Claude bypassPermissions, Codex danger-full-access, Grok --always-approve, opencode --auto, omp --yolo. A node can therefore run any command its agent decides to run, with your credentials and your machine's reach. The per-node git worktree isolates the branch it commits to, not the filesystem, the network, or anything else outside it. Only launch nodes whose task you would trust to run unsupervised, and prefer a sandboxed or otherwise disposable host for anything else.

Source: https://github.com/plasma-ai/fractal

Package: https://pypi.org/project/plasma-fractal/

Documentation: https://docs.plasma.ai/fractal

Installation

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.

Skill

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).

Usage

A fractal is a tree of git worktrees, each running an autonomous agent loop. The root (user) node is your current branch itself — it 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 (or, with --headless, in detached process groups), 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. On hosts where tmux cannot run, add --headless; the node's output appends to headless.log, delegated child starts follow the parent's backend, and an unflagged relaunch reuses the backend the node last launched with.

Parameters the skill interprets from the directive:

Development

Install

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).

Tests

Run the test suite:

pytest .

The suite runs with --doctest-modules enabled, and the integration tests create real git repositories and worktrees.

Linting

Run linters and formatters:

pre-commit run --all-files

Contributing

The contribution workflow, repository conventions, and release process (version sources, tagging, CI guard) are documented in:

Pull requests should be branched from dev, not main, and opened against dev — main only advances at releases.

License

Licensed under the Apache License 2.0 — see LICENSE.

Copyright © 2026 Plasma AI

fractal (plasma-ai/fractal)

Searching Database…

782 ·GitHub
Fractal
What is this?Fractal spawns autonomous coding-agent loops that arrange themselves into a tree: each node iterates toward a goal in its own git worktree and can spawn child nodes for subtasks, letting the tree grow to fit the problem instead of following a fixed plan.
Is this a CLI tool or something else?It's a Python CLI package (the fractal command) plus a terminal dashboard. All run state (runs, iterations, steps, costs) is tracked in a single local SQLite database that you browse live via the TUI.
How do I install and start using it?Install the fractal package from PyPI (or via pipx/uv tool install), then run fractal open from your project root to launch the dashboard. Agent skills can be added via the plugin marketplace or by running fractal install to copy them into ~/.claude/skills and ~/.agents/skills.
Which coding agents does it work with?Five agent backends are supported, selected per node with --agent: Claude Code, Codex, Grok Build, OpenCode, and Oh My Pi. Claude and Codex can also route through OpenRouter for model access, and each node needs a tmux session (or --headless mode if tmux isn't available).
What's the biggest risk to know about before running this?By default every seeded agent config disables the approval gate (Claude bypassPermissions, Codex danger-full-access, Grok --always-approve, etc.), so a node can run any command its agent decides on with your credentials and machine access. The per-node git worktree only isolates commits to its branch, not the filesystem or network, so untrusted tasks should run on a sandboxed or disposable host.
Who is this built for?Developers comfortable running unattended, permission-bypassing coding agents who want to scale a single task into a tree of cooperating agent loops, with hard caps on iterations, depth, cost and time to keep things bounded.
How does fractal control cost per agent loop?You can set per-run, per-iteration, and per-step cost ceilings (max-cost, max-iter-cost, max-step-cost) plus a reserve-budget for cleanup; since runs are isolated, each launch arms the cap anew, and node start --continue refuses without an explicit --max-cost after a budget-ended run.
Can nodes run without tmux?Yes, pass --headless to run a node as a detached process group instead of a tmux session, with output appended to headless.log.
How do I spawn and manage nodes day to day?Use the /fractal skill with a plain-language directive inside your agent; it infers parameters like name, scope, budget, and timeouts, asks for anything missing, then launches the node once you approve.
What isolation does a node's git worktree actually provide?It isolates the branch the node commits to, not the filesystem, network, or anything else outside the worktree — so dangerous tasks still need a sandboxed or disposable host.
What are similar projects?openrig, swarm-forge, ClawTeam, codify, MiMo-Code, shipyard, hive, emdash
Which topics is it in?cost-tracking, git-worktrees, tmux, pypi, openrouter, agent-harness, grok, autonomous-agents, tui, orchestration, agent-orchestration, git
Creator
plasma-ai
Size
8.3 MB
Stars
782
Updated
CommitSep 17
Age
3mo
Commits · 90 Days