fractal
Fractal is a tool that organizes autonomous agent loops into a hierarchical tree of git worktrees, where each node iterates toward a goal and spawns child nodes for subtasks. It solves the problem of scaling agentic workflows beyond a single loop by dynamically growing the tree to fit the problem, with hard caps on iterations, depth, children, cost, and time. It is for developers who want to run bounded, unattended multi-agent tasks with monitoring and control.
✨ Key features
- Recursive self-organization into a tree of agent loops
- Each node runs in its own git worktree with tmux sessions
- Supports Claude Code, Codex, Grok, OpenCode, and Oh My Pi
- Hard caps on iterations, depth, children, cost, and time
- All run metadata stored in a local SQLite database
- Live terminal UI dashboard via 'fractal open'
🎯 Use cases
- Decomposing a large coding task into parallel subtasks handled by child agents
- Running bounded autonomous coding loops with cost and time limits
- Monitoring and steering multiple agent runs from a terminal dashboard
- Integrating agent skills into Claude Code or Codex via plugin marketplace
📦 Installation
🧰 Requirements: Requires Python and pip; supports macOS/Linux (assumed). Optional API keys for agents (e.g., Anthropic, OpenAI) and OpenRouter if used.
pip install plasma-fractal
or
pip install fractal
For isolated environments, use pipx install or uv tool install, and also install plasma-wiki (plain pip pulls it automatically). For uv: uv tool install plasma-fractal --with-executables-from plasma-wiki.
Open dashboard with fractal open (requires initialized fractal).
🚀 Usage
# Initialize a fractal in your project root (if not already)
# Then open the dashboard
fractal open
# Use the /fractal skill in Claude Code or Codex to spawn nodes
# Example directive: /fractal implement feature X with max-iters 10
⚠️ Good to know
Nodes run agents without permission prompts by default, which can execute arbitrary commands with your credentials; use only on trusted tasks and prefer sandboxed hosts.
❓ FAQ
What agent backends are supported?
Claude Code, Codex, Grok Build, OpenCode, and Oh My Pi are supported, selected per node with --agent.
How do I install the skill for Claude Code or Codex?
Use the plugin marketplace: for Claude Code run /plugin marketplace add plasma-ai/plugins then /plugin install fractal@plasma; for Codex run codex plugin marketplace add plasma-ai/plugins then codex plugin add fractal@plasma.
Can I set a cost limit for a run?
Yes, use the max-cost parameter to set a cost ceiling in USD per run. After a budget-ended run, node start --continue requires an explicit --max-cost.
What is the default behavior for agent permissions?
By default, nodes run their agent without permission prompts, disabling approval gates (e.g., bypassPermissions, danger-full-access). This is a security risk, so only launch trusted tasks.
📊 Repository
🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.