Getting Started#

Fractal runs trees of autonomous coding-agent nodes. Each node is an isolated git worktree driven by an iteration loop in a tmux session, with lifecycle, budgets, and inter-node messaging all recorded in one central SQLite database per tree. This page walks a first session end to end: install the package, initialize a repository, create and start one node, watch it work, and merge the result.

Installation#

Package#

Install from PyPI:

$ pip install plasma-fractal

plasma-fractal is the real package. The fractal project on PyPI is a metadata-only pointer distribution containing no code — just an exact plasma-fractal==<version> pin that bumps in lockstep with every release — so pip install fractal installs the same thing. The pointer begins at version 1.0.0; earlier releases under the fractal name on PyPI are an unrelated package.

A plain pip install pulls the plasma-wiki dependency and puts its wiki executable on your PATH; fractal shells out to it to maintain the project wiki during commits. Isolated installers do not expose the wiki executable automatically — with pipx, install plasma-wiki separately; with uv, one command covers both:

$ uv tool install plasma-fractal --with-executables-from plasma-wiki

Agent skills#

The /fractal skill drives node creation conversationally from inside Claude Code or Codex (see The Fractal Skill). Install it from the plugin marketplace (/plugin marketplace add plasma-ai/plugins then /plugin install fractal@plasma in Claude Code; the codex plugin equivalents in Codex), or from the CLI:

$ fractal install
Installed fractal -> /home/user/.claude/skills/fractal.
Installed fractal -> /home/user/.agents/skills/fractal.
Installed wiki -> /home/user/.claude/skills/wiki.
Installed wiki -> /home/user/.agents/skills/wiki.

fractal install copies the bundled fractal and wiki skills into the Claude Code (.claude/skills) and Codex (.agents/skills) skill directories under your home directory, replacing any prior copy of the same skill. The wiki skill ships with fractal’s plasma-wiki dependency and installs alongside. These flags modify the behavior:

--project (default: off)

Install into the current directory instead of the home directory.

--link (default: off)

Symlink the skills instead of copying them. This requires the package files on disk (e.g. an editable install); a zipped install refuses. Source edits then apply without re-installing.

After upgrading the package, re-run fractal install to refresh copied skills.

Prerequisites#

  • git — fractal anchors to a git repository; fractal init bootstraps one when run outside a repo (git init on a project-named branch plus an initial commit of an empty .gitignore), and refuses a detached HEAD.

  • tmux — every node loop runs in a detached tmux session; fractal node start errors when tmux is missing. tmux 3.2 or newer is needed to forward provider keys into an already-running tmux server; on older versions the loop’s preflight reports the missing key instead.

  • A provider CLI — the agent command a node is configured with must be on PATH: claude (Claude Code), codex (Codex), grok (Grok Build), opencode (OpenCode), or omp (Oh My Pi). See Agent Backends.

  • The ``wiki`` CLI — from plasma-wiki, used during the commit pipeline; a plain pip install provides it (see above for pipx and uv tool installs).

  • ``OPENROUTER_API_KEY`` — only when routing an agent through --provider=openrouter; the key is read from the launching shell and captured into the node’s tmux session, so rotating it requires a node restart.

Initializing a repository#

Run fractal init once at the repository root — or, in a monorepo, point it at a sub-project folder:

$ cd myproject
$ fractal init --agent=claude
Initialized user node on branch main
Created .fractal/main/ (config, database, radio) and the project wiki at wiki/
Next: commit the baseline: fractal commit "<message>" --init

fractal init takes an optional path argument (default .) and these options:

--agent (default: unset)

The default agent command spawned nodes inherit: claude, codex, grok, opencode, or omp. An unknown name refuses at init.

--provider (default: the vendor-native endpoint)

The default provider route spawned nodes inherit (e.g. openrouter).

It creates the user node — the passive root of the tree, anchored to the branch you are on. Concretely, it writes:

  • .fractal/<branch>/ — the user node’s data directory, holding config.json and the central SQLite database (.db) that records the whole tree;

  • wiki/ — the project wiki scaffold, if one does not already exist (a committed knowledge base shared by all nodes);

  • a repo-local git exclude block (in .git/info/exclude), so fractal’s runtime artifacts stay out of your commits by default (fractal track opts the seed directory back in).

The user node never runs a loop — you (or your agent, via the skill) act as its operator. Re-running fractal init is idempotent: it updates the agent and provider defaults and repairs missing pieces without clobbering anything.

Finish setup by committing the baseline. A node worktree branches from the last commit on its base branch, so the wiki scaffold must be committed before the first node is created:

$ fractal commit "add project wiki" --init

--init labels this a baseline commit — the only kind of commit a user node accepts. See Architecture for how the tree, worktrees, and database fit together.

Creating a first node#

fractal node init <name> creates an agent node: a git worktree checked out on branch <parent>.<name> under .worktrees/, plus a node data directory seeded with its task contract (NODE.md), iteration steps, scripts, and skills. Node names are single branch segments — letters, digits, and underscores.

Always cap a new node: budgets default to unlimited, and one iteration is several agent invocations. The command warns on stderr when neither --max-cost nor --max-iters is given (unless the agent’s spend is untracked — e.g. codex without a priced model).

$ fractal node init parser --title="Build the parser" --max-iters=10 --max-cost=10.0
Initialized /home/user/myproject/.worktrees/main.parser

Next: author the node's task in /home/user/myproject/.worktrees/main.parser/.fractal/main.parser/NODE.md
(its Instructions and Completion Requirements sections start blank),
then start the loop: fractal node start main.parser

--max-iters caps the iterations per run, and --max-cost sets the run’s cost ceiling in USD (shared with any descendants the node spawns). fractal node init accepts many more options — agent, provider, model, and effort overrides, time budgets, commit scope, pacing, child caps — all of which land in the node’s config.json and can be edited before launch. The full surface is covered in Configuration and fractal node.

Now author the node’s task in its NODE.md. Two sections start as blank placeholders:

  • ## Instructions — the node’s goals and directions.

  • ## Completion Requirements — the conditions under which the node is done. The seed instructs the node to run fractal node finish in the iteration that meets them; a node whose requirements are left empty never self-completes, so cap open-ended work with --max-iters.

## Instructions

Implement the parser module described in <spec-file>, with unit tests
covering the happy path and error recovery.

## Completion Requirements

The test suite passes and the module is committed. Then run
`fractal node finish --reason="parser complete"`.

Starting the node#

$ fractal node start parser
Started tmux session: myproject (main-parser)

The loop launches in a detached tmux session named <repo> (<branch>) with dots flattened to dashes. Anywhere a command takes a node branch, a unique trailing segment works — parser resolves to main.parser. Run parameters come from config.json; the only launch-time flags are for re-arming a settled node (--continue, with --clean to discard uncommitted project files and --max-cost to retune the budget) — see Node Lifecycle.

Warning

Nodes run their agents with elevated permissions by design (e.g. Claude Code’s bypassPermissions, Codex’s danger-full-access). Only launch tasks you trust with your repository and machine.

Watching it run#

From cheapest to richest:

  • fractal node status parser prints the node’s lifecycle status — active while the loop runs, decorated with any pending signal (e.g. active (finishing)) and, when a run lands exited, with the recorded reason (exited (<reason>)).

  • fractal node activity parser prints the lifecycle timeline — runs, iterations, steps, and events with durations and per-step costs, most recent first.

  • fractal node attach parser attaches your terminal to the node’s live tmux session (the node must be active); detach with the standard tmux detach.

  • fractal open launches the TUI cockpit — the whole tree, radio traffic, budgets, and event logs on one live screen; see The TUI.

From the repo root, fractal node list tables every agent node under the root with its status, caps, and the age of its last activity, and fractal node cost spent parser reports the run’s recorded spend. Nodes also report progress over the radio — see Radio.

Finishing and merging#

A well-authored node ends itself: when its Completion Requirements are met, it runs fractal node finish from inside its loop and settles as completed. You can also end it from outside:

$ fractal node finish parser --reason="good enough"

finish ends the node gracefully after the current iteration; fractal node stop ends it after the current step; fractal node kill reaps it immediately. The signal tiers, pausing, and continuation are covered in Node Lifecycle.

Once fractal node status parser reads completed, merge the work:

$ fractal node merge parser

merge squash-merges the node’s branch into its merge target — its configured base, or by default the parent branch (here main). One squash commit lands on the target; the node’s full iteration history stays on its own branch. Merging refuses while the node — or the target — is active or paused.

From here the node can be re-armed for further iterations with fractal node start parser --continue, or removed with fractal node delete parser — the worktree and branches go, while the node’s history in the central database persists.

Where next#

The rest of the guide goes deeper on each piece: Architecture explains how the tree, worktrees, branches, and central database fit together; Node Lifecycle covers statuses, signals, pause and resume, continuation, and teardown; The Iteration Loop walks what happens inside an iteration — steps, sync, and the commit pipeline; Agent Backends describes the agent backends and provider routing; Radio covers inter-node messaging; and Plans and Steps covers plan files. Beyond the guide, Configuration documents every configuration key, Command-Line Interface is the full command reference, The Fractal Skill documents the /fractal plugin skill, Recipes collects common operator tasks, and Examples includes a scripted version of this walkthrough that builds a ready-to-start node in a scratch repository.