Skip to content
Back to search

fractal

Hierarchical agent loops with recursive self-organization.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/plasma-ai/fractal with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/plasma-ai/fractal'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/plasma-ai--fractal/badge.svg)](/listings/plasma-ai--fractal)

HTML

<a href="/listings/plasma-ai--fractal"><img src="/api/listings/plasma-ai--fractal/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/plugin.json · Manifest · 14 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "fractal",
  3. "displayName": "Fractal",
  4. "version": "1.4.0",
  5. "description": "Hierarchical agent loops with recursive self-organization.",
  6. "author": {
  7. "name": "Plasma AI",
  8. "email": "eng@plasma.ai",
  9. "url": "https://plasma.ai"
  10. },
  11. "skills": ["./fractal/skills"],
  12. "repository": "https://github.com/plasma-ai/fractal",
  13. "keywords": ["fractal"]
  14. }
README.md · README · 241 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # fractal
  2. [![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/plasma-ai/fractal/blob/main/LICENSE)
  3. [![build](https://github.com/plasma-ai/fractal/actions/workflows/build.yaml/badge.svg)](https://github.com/plasma-ai/fractal/actions/workflows/build.yaml)
  4. [![docs](https://github.com/plasma-ai/fractal/actions/workflows/docs.yaml/badge.svg)](https://github.com/plasma-ai/fractal/actions/workflows/docs.yaml)
  5. [![lint](https://github.com/plasma-ai/fractal/actions/workflows/lint.yaml/badge.svg)](https://github.com/plasma-ai/fractal/actions/workflows/lint.yaml)
  6. [![tests](https://github.com/plasma-ai/fractal/actions/workflows/tests.yaml/badge.svg)](https://github.com/plasma-ai/fractal/actions/workflows/tests.yaml)
  7. [![codecov](https://codecov.io/gh/plasma-ai/fractal/branch/main/graph/badge.svg?token=FB0T12O2ZP)](https://codecov.io/gh/plasma-ai/fractal)
  8. [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
  9. Hierarchical agent loops with recursive self-organization.
  10. In a fractal, autonomous agent loops arrange themselves into a tree: a node
  11. iterates toward a goal in its own `git worktree` and spawns child nodes for
  12. separable subtasks, so the tree grows to fit the problem rather than a fixed
  13. plan. Hard caps (iterations, depth, children, cost, time) keep each loop
  14. bounded, and an operator can steer or stop it at any point. Run metadata
  15. (including cost) lands in one local `SQLite` database, which can be interacted
  16. with live in a terminal UI.
  17. ![fractal TUI dashboard](https://raw.githubusercontent.com/plasma-ai/fractal/main/docs/_static/tui.png)
  18. > [!WARNING]
  19. > **Nodes run their agent without permission prompts by default.** Unattended
  20. > loops cannot stop to ask, so every seeded agent config disables the approval
  21. > gate — Claude `bypassPermissions`, Codex `danger-full-access`, Grok
  22. > `--always-approve`, opencode `--auto`, omp `--yolo`. A node can therefore run
  23. > any command its agent decides to run, with your credentials and your machine's
  24. > reach. The per-node `git worktree` isolates the *branch* it commits to, not
  25. > the filesystem, the network, or anything else outside it. Only launch nodes
  26. > whose task you would trust to run unsupervised, and prefer a sandboxed or
  27. > otherwise disposable host for anything else.
  28. ______________________________________________________________________
  29. **Source**:
  30. [https://github.com/plasma-ai/fractal](https://github.com/plasma-ai/fractal)
  31. **Package**:
  32. [https://pypi.org/project/plasma-fractal/](https://pypi.org/project/plasma-fractal/)
  33. **Documentation**:
  34. [https://docs.plasma.ai/fractal](https://docs.plasma.ai/fractal)
  35. ______________________________________________________________________
  36. ## Installation
  37. Install the `fractal` package from PyPI:
  38. ```bash
  39. pip install plasma-fractal
  40. ```
  41. or
  42. ```bash
  43. pip install fractal
  44. ```
  45. Use `pipx install` or `uv tool install` to install the package in an isolated
  46. environment. If you use one of these two methods, you must also install
  47. `plasma-wiki` (a plain `pip` install pulls `plasma-wiki` and puts `wiki` on your
  48. `PATH`, but this is not the case when using `pipx install` or
  49. `uv tool install`).
  50. `uv tool install plasma-fractal --with-executables-from plasma-wiki` does the
  51. same in one command.
  52. Open the dashboard from your project root with `fractal open` (requires an
  53. initialized fractal). Pass `--light` if your terminal uses a light color scheme.
  54. ### Skill
  55. Install the skill for your agent via the plugin marketplace (Claude Code and
  56. Codex):
  57. ```bash
  58. # Claude Code
  59. /plugin marketplace add plasma-ai/plugins
  60. /plugin install fractal@plasma
  61. # Codex
  62. codex plugin marketplace add plasma-ai/plugins
  63. codex plugin add fractal@plasma
  64. ```
  65. Another install route is from the CLI, which copies (or symlinks) the fractal
  66. and wiki skills into `~/.claude/skills` and `~/.agents/skills` (add `--project`
  67. for the current project only):
  68. ```bash
  69. fractal install [--link]
  70. ```
  71. After upgrading the package, re-run `fractal install` to refresh the copied
  72. skills (pass `--link` for symlinked install).
  73. ## Usage
  74. A fractal is a tree of git worktrees, each running an autonomous agent loop. The
  75. root (user) node is your current branch itself — it has no worktree or loop of
  76. its own; top-level nodes branch from it, and child nodes branch from their
  77. parent. Agents iterate in tmux sessions (or, with `--headless`, in detached
  78. process groups), and all state (runs, iters, steps, costs, signals) is tracked
  79. in a local SQLite database.
  80. Five agent backends are supported — Claude Code (`claude`), Codex (`codex`),
  81. Grok Build (`grok`), OpenCode (`opencode`), and Oh My Pi (`omp`) — selected per
  82. node with `--agent` (children inherit it). Claude and Codex can additionally
  83. route through OpenRouter with `--provider=openrouter`, which authenticates via
  84. `OPENROUTER_API_KEY` from the launching shell; OpenCode and Oh My Pi reach
  85. OpenRouter natively through their own `openrouter/<author>/<model>` model ids.
  86. Use the `/fractal` skill to spawn and manage agent nodes. The `fractal` CLI is
  87. also available directly — run `fractal --help` and `fractal <command> --help` to
  88. explore.
  89. The skill is invoked as `/fractal [directive]` and takes plain-language
  90. instructions. The agent interprets the directive and prints any suggested
  91. `NODE.md` instructions and completion requirement it can distill from the
  92. directive, plus a table of every parameter (empty where the directive said
  93. nothing), then asks for anything it could not infer. From there it walks you
  94. through refining the node's definition and, once you approve, launches the node
  95. in a tmux session. On hosts where tmux cannot run, add `--headless`; the node's
  96. output appends to `headless.log`, delegated child starts follow the parent's
  97. backend, and an unflagged relaunch reuses the backend the node last launched
  98. with.
  99. Parameters the skill interprets from the directive:
  100. - **`name`**: node name (required; letters, digits, and `_` only — no `-`)
  101. - **`path`**: project root, repo root or monorepo sub-project (default: `.`)
  102. - **`title`**: human-readable display name (default: de-slugged node name)
  103. - **`scope`**: restrict commits to subdirectories within the worktree
  104. (comma-separated, e.g. `parent/child,tests`)
  105. - **`base`**: branch to start from (default: current branch)
  106. - **`meta`**: target node branch for meta-configuration
  107. - **`inherit`**: seed surfaces from the parent node instead of the package seed
  108. (comma-separated: `steps`, `scripts`, `skills`, `config`, or `all`); agent
  109. config always inherits. A top-level spawn's parent is the user node, which
  110. carries no steps, scripts, or skills — the parameter is for configured nodes
  111. spawning children
  112. - **`agent`**: agent command; inherits the user node's default when omitted
  113. - **`provider`**: provider route for the agent (e.g. `openrouter`); inherits the
  114. user node's default when omitted
  115. - **`model`**: model override; when omitted, the agent uses its own default
  116. model (Claude runs on the seed's `best` alias, or
  117. `anthropic/claude-sonnet-4.6` when routed through OpenRouter)
  118. - **`effort`**: reasoning-effort override; when omitted, the Claude and Codex
  119. seeds' own pinned level (`high`) applies rather than the vendor default, while
  120. Grok, OpenCode, and Oh My Pi fall back to the vendor default
  121. - **`max-iters`**: per-run iteration cap
  122. - **`max-depth`**: maximum child node nesting depth
  123. - **`max-children`**: maximum direct child nodes
  124. - **`max-descendants`**: maximum total descendant nodes
  125. - **`timeout`**: per-run time limit (e.g. `30m`, `1.5h`)
  126. - **`iter-timeout`**: per-iteration time limit (e.g. `30m`, `1.5h`)
  127. - **`step-timeout`**: per-step time limit (e.g. `30s`, `10m`); caps each step
  128. - **`interval`**: fixed iteration schedule (e.g. `1h`)
  129. - **`sleep`**: delay between iterations (e.g. `10s`)
  130. - **`wait`**: sleep between approval-wait sync invocations (default: `1m`)
  131. - **`max-cost`**: cost ceiling in USD per run — runs are isolated, so each
  132. launch arms the cap anew; after a budget-ended run, `node start --continue`
  133. refuses without an explicit `--max-cost`
  134. - **`max-iter-cost`**: per-iteration cost ceiling in USD
  135. - **`max-step-cost`**: per-step cost ceiling in USD (warn-only when
  136. unenforceable)
  137. - **`reserve-budget`**: budget reserved for cleanup; USD or N% of `max-cost`
  138. (default: 10%)
  139. - **`sync`**: enable (default) or disable radio sync before each step
  140. - **`detached`**: run each step as a separate agent session (default: one
  141. continuous session)
  142. - **`local`**: skip pushing to remote after each commit
  143. ## Development
  144. ### Install
  145. Run `install.sh` in the package root. With no environment active it creates and
  146. uses a local `.venv`; with one active (e.g. pyenv) it installs into that
  147. environment (editable), without recreating it:
  148. ```bash
  149. ./install.sh --all-extras --groups=test,lint,type
  150. ```
  151. Run `./install.sh --help` for all options. Alternatively, run
  152. `uv sync --all-extras --group test --group lint --group type` and
  153. `uv run pre-commit install` to set up the environment manually.
  154. Installing a dependency as editable (e.g. a sibling package) is left to the
  155. caller: `uv pip install --editable <path>`.
  156. With an editable install, `fractal install --link` symlinks the bundled skill
  157. into the agent skill directories instead of copying it, so skill edits apply
  158. without re-running the install.
  159. Once installed, run tools with `uv run --no-sync <command>`, or activate the
  160. environment first (`source .venv/bin/activate`).
  161. ### Tests
  162. Run the test suite:
  163. ```bash
  164. pytest .
  165. ```
  166. The suite runs with `--doctest-modules` enabled, and the integration tests
  167. create real git repositories and worktrees.
  168. ### Linting
  169. Run linters and formatters:
  170. ```bash
  171. pre-commit run --all-files
  172. ```
  173. ### Contributing
  174. The contribution workflow, repository conventions, and release process (version
  175. sources, tagging, CI guard) are documented in:
  176. - Contribution workflow (organization-wide):
  177. [CONTRIBUTING.md](https://github.com/plasma-ai/.github/blob/main/CONTRIBUTING.md)
  178. - Repository conventions:
  179. [AGENTS.md](https://github.com/plasma-ai/fractal/blob/main/AGENTS.md)
  180. - Release process (organization-wide):
  181. [RELEASING.md](https://github.com/plasma-ai/.github/blob/main/RELEASING.md)
  182. Pull requests should be branched from `dev`, not `main`, and opened against
  183. `dev` — `main` only advances at releases.
  184. ## License
  185. Licensed under the Apache License 2.0 — see
  186. [LICENSE](https://github.com/plasma-ai/fractal/blob/main/LICENSE).
  187. Copyright © 2026 Plasma AI

Version history

  • v1.4.010/26/2026

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.