fractal

name

fractal

description

Delegate analysis- and context-heavy work to Fractal, an agentic CLI powered by a self-harnessed Recursive Language Model (predict-rlm), by running it non-interactively (fractal -p). Reach for it when a task needs reasoning over a large or deep codebase, synthesizing an answer across many files, auditing, or open-ended investigation — work that would otherwise flood your own context. The RLM reasons over context programmatically (no context rot) and returns a distilled answer. Use when asked to run Fractal headless, script it, call it from CI or another agent, or offload a heavy analysis/large-context task. Less suited to trivial single-file edits you can do directly.

Fractal headless mode

Fractal is an agentic CLI powered by predict-rlm, a self-harnessed Recursive Language Model runtime. Each invocation runs one RLM turn: it mounts the workspace into a Docker sandbox, lets the model write and run its own code to read/edit files and run commands, then prints a final answer. Headless mode is fractal -p "<task>".

Install Fractal (if needed)

Before anything else, check that the fractal command exists, and install it if it doesn't:

command -v fractal >/dev/null 2>&1 \
  && fractal --version \
  || curl -LsSf https://fractal.trampoline.ai/install.sh | sh

The installer bootstraps uv if needed, installs Fractal as an isolated tool, and puts fractal on the PATH. If it was just installed in this shell, fractal may not be on the PATH until you start a new shell or re-source your profile.

Fractal also needs, at runtime:

• Docker, running — every turn executes in a Docker sandbox.
• The sbx CLI v0.33.0+, logged in, with a default network policy — brew install docker/tap/sbx && sbx login && sbx policy set-default balanced.
• A configured model provider — verify with the Preflight checks below.

When to reach for it

An RLM reasons over context programmatically — it greps, reads, and slices files in code instead of loading everything into one prompt — so it handles large or deep inputs without context rot. Defer to Fractal when a task is analysis- or context-heavy and would otherwise flood your own context:

• "Trace how a request flows through this 200-file service, end to end."
• "Audit this repo for X across every file and summarize the findings."
• "Read these logs / this diff / these docs and tell me the root cause."
• Synthesis or Q&A over a directory too big to pull into your own window.

It also works as a general coding agent (fix a bug, make tests pass) — use that when convenient. But skip it for trivial, local edits you can do yourself in a file read or two: each turn is slow (minutes) and separately billed, so the payoff is in the heavy jobs.

Quick start

fractal -p "Trace how a request flows through this service, end to end" --workspace /path/to/project

• stdout = the agent's final response text, nothing else.
• stderr = banner, progress, changed files, usage/cost, completion status.
• Capture the two streams separately so you can use the response while still reading diagnostics: out=$(fractal -p "..." 2>err.log).

Preflight (do once per machine/session)

docker info >/dev/null || echo "start Docker first"   # sandbox needs the daemon
sbx version                                            # must be v0.33.0+
sbx diagnose                                           # login/install health
sbx policy set-default balanced                        # required before sbx create
sbx template ls                                        # empty output means first startup pulls the template image
fractal config status                                  # provider/model/auth ok?

If config is missing, fractal config setup is interactive — in automation use fractal config set ... or the FRACTAL_PROVIDER / FRACTAL_MODEL env vars.

Troubleshooting Fractal startup

When a user asks you to troubleshoot a Fractal install or startup failure, check the local prerequisites before trying a fractal -p run. If Fractal seems to stall on startup, or reaches a timeout, most failures are bad sbx setup:

1. Run sbx version. Fractal requires sbx v0.33.0 or newer. If the command is missing or too old, install or upgrade with brew install docker/tap/sbx or brew upgrade docker/tap/sbx.
2. Run sbx diagnose. If it reports an auth problem, ask the user to run sbx login in their terminal.
3. Run sbx policy set-default balanced. Fractal needs a default network policy before sbx create; without one, first launch can open browser login and then appear to hang while sbx waits for an interactive policy choice.
4. Run sbx template ls. If no templates appear, the sandbox template image has not been pulled yet, so the first Fractal startup can take longer while sbx downloads it.
5. Run fractal config status after sbx is healthy to verify provider, model, and auth configuration.

Output contract

Channel	Content
stdout	Final response text only (trailing newline guaranteed)
stderr	fractal: session <id>, progress events, fractal: changed files a.py, b.py, fractal: usage N in / M out tokens, $X, fractal: complete
exit 0	Turn completed
exit 1	Setup/runtime error (fractal: failed: ... on stderr)
exit 2	Hit --max-iterations; best-effort response still on stdout
exit 130	Interrupted (Ctrl-C / SIGINT)

For scripting, capture streams separately: out=$(fractal -p "..." 2>err.log).

Key flags

• --workspace DIR — directory the agent edits. Always pass it explicitly; default is the cwd.
• --json — print one machine-readable result object to stdout instead of plain text (session_id, status, response, changed_files, usage, error). Pair with --quiet for stdout-only JSON. See RECIPES.md.
• --quiet — suppress all stderr. Stdout-only, but you lose progress, the session id, changed-files, and cost. Prefer capturing stderr to a file over --quiet when you need to resume or audit.
• --verbose — full per-iteration trace (reasoning, code, output) on stderr. Use when debugging why a turn did something.
• -p - — read the whole prompt from stdin (fails fast if stdin is empty). Piping stdin alongside a normal -p "..." instead appends it as context: git diff | fractal -p "review this diff".
• --resume SESSION_ID — continue a prior session (multi-turn memory works headless). Get the id from the stderr line fractal: session <id>, or the newest file in <workspace>/.fractal/sessions/.
• --include DIR — mount extra read/write dirs into the sandbox (repeatable).
• --lm / --sub-lm / --max-iterations — per-run overrides; env equivalents FRACTAL_MODEL, FRACTAL_SUB_MODEL, FRACTAL_MAX_ITERATIONS.

Tips for reliable runs

• fractal: command failed: ... lines on stderr are the agent probing (e.g. trying pytest variants), not failures — trust the exit code and any fractal: failed: line.
• Validate model ids with fractal config status before a run, so a typo is caught up front rather than mid-turn.
• For structured output, ask for it in the prompt (e.g. "respond with only a JSON array of …"), or run in a clean git tree and diff it afterwards to see exactly what changed.

See RECIPES.md for copy-paste patterns: CI gate, multi-turn driver, diff review, structured output.