fractal: agent trees where every approval gate is off, and the only isolation is a branch

Every approval gate is disabled, because a loop that cannot ask still has to run

The repository's most important paragraph is a warning, and it explains the whole architecture in one breath. Nodes run their agent without permission prompts by default. The reason given is structural rather than careless: an unattended loop cannot stop to ask a question, so every seeded agent configuration disables the approval gate, one specific setting per backend, and five backends are supported. The consequence is stated without hedging. A node can run any command its agent decides to run, with your credentials and your machine's reach. That is the honest framing, and it is worth holding on to while reading the feature list, because every subsequent parameter about depth, children and cost is a bound on how much work happens, not a bound on what the work may do. There is no allow-list of commands, no filesystem confinement, and no network policy anywhere in the visible documentation. The recommended mitigation is also stated plainly: only launch nodes whose task you would trust to run unsupervised, and prefer a sandboxed or disposable host for anything else.

A scope list is the only containment lever, and node names cannot contain dashes

Among roughly twenty parameters, exactly one narrows what a node may touch. The scope parameter restricts a node's commits to named subdirectories within its worktree, given as a comma-separated list such as a parent and child pair plus a tests directory. That is a meaningful control and it is worth using, because the worktree otherwise hands a node the whole tree. Everything else in the parameter list bounds volume rather than reach: iteration caps, maximum nesting depth, maximum direct children, a cap on total descendants, per-run, per-iteration and per-step time limits, and cost. One naming rule catches people out and is stated in parentheses. A node name accepts letters, digits and underscores only, with dashes explicitly rejected, which is unusual enough to be worth reading twice before you name a node after a branch, since the obvious spelling will be refused.

Skills are copied rather than linked, so an upgrade silently leaves them stale

The skill can be installed three ways. The plugin route points at a marketplace and installs the skill by name for either of two coding agent ecosystems. The CLI route runs a command that copies, or with a flag symlinks, the tool's own skills and the sibling wiki skills into the agent skill directories, optionally scoped to the current project rather than your home directory. The default is a copy, and the documentation then tells you what to do about it: after upgrading the package, re-run the install command to refresh the copied skills, using the link form if you installed that way. That is documented, which is more than most tools manage, and it is still a footgun, because the common sequence is install, upgrade, keep working. A symlinked install would have made the upgrade automatic at the cost of a copy step, and the choice is offered rather than made for you.

Two names on the package index, and a sibling executable the isolated installers drop

The install section offers the package under two names, and then complicates it:

pip install plasma-fractal

Installing normally pulls a sibling package and puts an executable called wiki on your path, which the dashboard apparently needs. Installing with an isolated tool installer, the kind that puts the tool in its own environment, does not pull that sibling, so the dashboard breaks. The documentation knows this and gives the one-command form that requests the sibling's executables alongside the install. The result is a tool whose headline install is two words, whose dashboard path has a hidden companion, and whose isolated install has a different invocation, all because of one shared executable. Both package names resolving to the same project also means the naming is a choice the index made for you, and if you script an environment you should pick the longer name and pin it.

Effort and model defaults differ per backend, and the difference is spelled out

Two parameters have no single default, and the documentation is precise about the divergence. Effort, which controls reasoning depth, falls back to a pinned level for two of the five backends, both seeded at a high level rather than the vendor default, while the other three fall back to whatever the vendor chooses. So the same node definition can think harder or think more cheaply depending on which agent you pointed it at, with no warning at run time. Model behaves the same way: omitted, the agent uses its own default, except that one backend runs on an alias defined in the seed and a different one applies when routed through a gateway. Two of the five backends can additionally be pointed at a model gateway, authenticating with a key taken from the launching shell, while the other two reach that gateway natively through their own model identifiers. If you are comparing runs across backends, normalise both parameters first.

The repository is itself a project template, with the update tool in its lint group

The dependency groups are worth reading for what they reveal. One holds documentation tooling, one holds linting, one is labelled security and contains a single vulnerability scanner, one holds the test stack including parallel execution, and one holds a type checker. The lint group contains three packages, and the third is a template-management tool, which is explained by a file at the repository root holding that tool's configuration. In other words this repository was generated from a template and keeps the generator so it can pull upstream template changes. That is a reasonable practice for a project that is itself a starting point, and it has a visible consequence: the same scaffolding, the same configuration files and the same opinionated defaults will appear in every repository the template produced, so two projects that both started here will share a maintenance surface. The root also carries plugin manifests for two agent ecosystems and a directory whose purpose the visible documentation never explains.

Python is bounded above, the classifiers are dynamic, and the example directory holds one script

The packaging declares a Python requirement with a floor and a ceiling, admitting three minor versions and refusing anything above the ceiling, which is a tighter contract than most projects state and worth respecting when you plan an upgrade. Its classifiers are declared dynamic rather than written inline, which means they are generated at build time, and they are held in a section belonging to a different build tool, with a single POSIX classifier. That combination works but it is unusual enough that a reader looking for the supported platforms in the usual place will not find them. The dependency list is short and disciplined, six packages with upper bounds, and it includes the sibling package discussed above plus the two libraries that produce the terminal interface and the command line. The examples directory, by contrast, is nearly empty: a placeholder file, a short readme, and one shell script.

Editorial conclusion

Read the warning first, because it is the design rather than a caveat. This tool exists to run agents unattended, and an unattended agent cannot stop to ask, so every seeded configuration for every supported backend starts with that backend's approval gate switched off. A node can therefore run any command it decides to run, with your credentials and your machine's reach, and the per-node worktree protects one thing only, the branch it commits to, not the filesystem, not the network, and not anything else outside it. If you want to use it, the containment levers are the ones it names: restrict a node's commits with a scope list, cap iterations, depth, children and time, and run the whole thing on a host you are willing to lose. The tooling itself is well made, with five agent backends, a local database covering runs and costs, and a terminal interface, so the question is never whether it works well. It is whether the task you are pointing at deserves a machine with your credentials and no guardrails.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. plasma-ai/fractal on GitHub
4. README