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…

783 ·GitHub
Fractal
Что это?Fractal порождает автономные циклы кодинг-агентов, которые сами выстраиваются в дерево: каждый узел движется к цели в собственном git worktree и может порождать дочерние узлы для подзадач, так что дерево растёт под задачу, вместо того чтобы следовать фиксированному плану.
Это CLI-инструмент или что-то другое?Это Python-пакет CLI (команда fractal) плюс терминальный дашборд. Всё состояние прогонов (запуски, итерации, шаги, затраты) отслеживается в единой локальной базе SQLite, которую вы просматриваете вживую через TUI.
Как установить его и начать пользоваться?Установите пакет fractal из PyPI (или через pipx/uv tool install), затем выполните fractal open из корня проекта, чтобы запустить дашборд. Навыки агентов можно добавить через маркетплейс плагинов или выполнив fractal install, чтобы скопировать их в ~/.claude/skills и ~/.agents/skills.
С какими кодинг-агентами он работает?Поддерживаются пять бэкендов агентов, выбираемых для каждого узла через --agent: Claude Code, Codex, Grok Build, OpenCode и Oh My Pi. Claude и Codex могут также направляться через OpenRouter для доступа к моделям, а каждому узлу нужна сессия tmux (или режим --headless, если tmux недоступен).
Какой главный риск нужно знать перед запуском?По умолчанию каждая стартовая конфигурация агента отключает шлюз одобрений (Claude bypassPermissions, Codex danger-full-access, Grok --always-approve и т. д.), поэтому узел может выполнить любую команду, на которую решится его агент, с вашими учётными данными и доступом к машине. Git worktree на узел изолирует только коммиты в своей ветке, но не файловую систему или сеть, так что недоверенные задачи следует запускать на хосте в песочнице или одноразовом.
Для кого это создано?Для разработчиков, которые спокойно запускают оставленных без присмотра кодинг-агентов в обход разрешений и хотят развернуть одну задачу в дерево сотрудничающих циклов агентов, с жёсткими лимитами на итерации, глубину, затраты и время, чтобы всё оставалось в рамках.
Как fractal контролирует затраты на каждый цикл агента?Можно задать потолки затрат на прогон, итерацию и шаг (max-cost, max-iter-cost, max-step-cost) плюс резервный бюджет (reserve-budget) для очистки; поскольку прогоны изолированы, каждый запуск заново активирует лимит, а node start --continue откажется работать без явного --max-cost после прогона, закончившегося из-за исчерпания бюджета.
Могут ли узлы работать без tmux?Да, передайте --headless, чтобы узел работал как отдельная группа процессов вместо сессии tmux, с записью вывода в headless.log.
Как порождать узлы и управлять ими в повседневной работе?Используйте навык /fractal с директивой на обычном языке внутри вашего агента; он выводит параметры вроде имени, охвата, бюджета и таймаутов, запрашивает недостающее, а затем запускает узел после вашего одобрения.
Какую изоляцию на деле даёт git worktree узла?Он изолирует только ветку, в которую узел делает коммиты, но не файловую систему, сеть или что-либо ещё за пределами worktree — так что опасные задачи всё равно требуют хоста в песочнице или одноразового.
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
783
Updated
CommitSep 17
Age
3mo
Commits · 90 Days