Loom is in pilot intake · these docs cover the full data-science lifecycle CLI Talk to us
Docs/Drive Loom/Plan mode

Plan mode

Toggle /plan to enter a read-only exploration phase. Loom can read files, run read-only bash, and run its read-only verbs to inspect the data — but writes, edits, spend, and irreversible actions are blocked until you toggle it back off. Use it to look before you leap: explore, have Loom propose a concrete lifecycle plan, then approve and execute.

Why a plan phase

For ambitious or expensive work — a full pipeline run, a GPU train, a promotion that ends in deploy — you want to understand the data and agree on a route before anything writes a new data object or spends a search budget. Plan mode gives the agent room to investigate while making the costly and irreversible steps physically unavailable.

The crucial difference from a generic editor "read-only mode": that kind of mode hardcodes its allowlist to read + bash, which would hide every Loom verb — so the agent couldn't actually look at your data while planning. Loom authors its own toggle whose allowlist is derived from its verb tiers, so the read-only data verbs stay on. You can profile, plot, validate, and check drift during planning; only the steps that write, spend, or mutate are withheld.

i

Plan mode is a planning aid, not a security boundary. The real enforcement is the tier-based approval gate that runs on every verb regardless of mode — deploy --apply, train --launch, and collab --send always gate. Plan mode is the lighter, voluntary lid you put on top while you think.

Toggle it with /plan

Inside the agent, /plan is a toggle — run it once to enter the planning phase, run it again to leave. Each switch is announced and the status surface shows a pill while you're in it:

loom                          # open the agent (interactive)
loom> /plan                    # Plan mode ON — read-only exploration
# ◆ planning (read-only)      ← status pill while the phase is active
loom> "survey this dataset and propose how we'd model it"
# … the agent explores with the read-only verbs and writes you a plan …
loom> /plan                    # Plan mode OFF — full lifecycle re-enabled

The state is persisted in the session: if you resume a transcript that was left in plan mode, Loom restores it (with a "plan mode restored (read-only)" note) so you never silently fall out of the lid you set. The toggle is interactive — the status pill and prompts render in the terminal UI, and in a headless run the toggle still applies but the visual surface is simply skipped.

What stays available

While plan mode is on, the active tool set is rebuilt to exactly two things: a read-only built-in shell, and Loom's read-only verbs. The verb list isn't a hardcoded constant — it's computed from the live tier map, so it always matches the catalog.

The read-only verbs

Every verb whose tier is read-only stays callable, so the agent can inspect the actual data — not just the filesystem — while it plans:

VerbWhat it inspects (read-only)
doctorhealth of the local Loom + Metaflow datastore stack
datasetsthe catalog of ingested Metaflow data objects
edaschema, missingness, target balance, correlations, leakage flags
vizdistributions, correlation, leaderboard plots from a data object or run
validateCV + sealed holdout + calibration + fairness + leakage → a VERDICT
reportan experiment's runs + metrics + lineage → a model-card
opsrun health, the leaderboard, and a data-object drift check
i

validate is in the allowlist on purpose. It's a read-only diagnostic — it computes a VERDICT but promotes nothing — so the agent can tell you whether an existing solution would even pass before you commit to the build-and-deploy route.

Read-only bash

The built-in shell stays on, but is narrowed to a read-only allowlist — inspection commands only, with no shell chaining or redirects (anything containing ;, &, backticks, a newline, or >/>> is refused):

# allowed: pure inspection
cat  ls  grep  find  head  tail  wc  pwd  echo  file  stat
du   df  which  env  printenv  uname  whoami  date
git status   git log   git diff   git show   git branch

# blocked: anything that writes, chains, or redirects
# mv … > out.csv      python train.py      rm -rf …      foo && bar

What's blocked

Three classes of action are withheld until you toggle off. A blocked call returns a clear reason rather than failing silently, so the agent (and you) know exactly why and how to proceed:

⚠

Plan mode also closes the boundary verb. ingest is the one door where outside data crosses into a Metaflow data object — it's workspace-write, so it's blocked in plan mode. If there's nothing in datasets yet, you'll plan against the catalog as it stands and ingest as the first executed step once you toggle off.

How the allowlist is derived

Loom doesn't keep a separate "plan-mode verb list" that could drift from reality. Every verb declares an approval tier, and that single source of truth drives both the always-on approval gate and plan mode's allowlist. When plan mode flips on, Loom filters the tier map to the read-only verbs and rebuilds the active tool set as exactly those plus the read-only shell:

TierExamplesIn plan mode
read-onlyeda, viz, report, ops, validate, datasets, doctoravailable
workspace-writefeatures, ingest, pipeline, collab (build)blocked
expensiverun / optimize, trainblocked
irreversibledeploy --apply, train --launch, collab --sendblocked

Because the list is computed, adding a new read-only verb makes it explorable in plan mode for free, and a new verb that writes or spends is withheld for free — no second list to keep in sync. See Lifecycle & verbs for the full tier matrix and the gate behavior outside plan mode.

The plan → approve → execute loop

The intended rhythm is three beats. First explore read-only, then read back a concrete plan, then toggle off and run it — gating only at the expensive and irreversible steps as usual.

loom> /plan
  # Plan mode ON — read-only exploration; writes & expensive/irreversible verbs blocked.

loom> "figure out how we'd predict is_fraud on IngestDataset/123"
  # Loom runs read-only verbs to investigate:
  loom doctor
  loom datasets
  loom eda --dataset IngestDataset/123 --target is_fraud
  loom viz --dataset IngestDataset/123 --kind all

  # … and proposes a concrete lifecycle plan, e.g.:
  # 1. features  (drop the two eda-flagged leakage columns, via --from)
  # 2. run       (AIDE search, --metric "maximize ROC-AUC", --steps 10) — EXPENSIVE
  # 3. validate  (sealed holdout + fairness on --sensitive region)
  # 4. deploy    (only if validate VERDICT == PASS) — IRREVERSIBLE, you confirm

loom> /plan
  # Plan mode OFF — full lifecycle re-enabled. Now the plan executes.

Because the agent profiled the data first, the plan it hands you is grounded in real schema and leakage findings — not a guess. When you toggle off, the same tier gate that was hidden behind plan mode takes over: workspace-write steps run with a one-line note, the expensive search gives you a heads-up, and the irreversible promotion still asks for a deny-first confirmation.

i

Plan mode pairs naturally with subagents. The data-scout persona does exactly this read-only recon as a focused child agent — profile shape, quality, and leakage, then propose a framing — and can never fire an expensive or irreversible verb either, so you can fan out the exploration without loosening the lid.

Headless and resumed sessions

The toggle behaves predictably outside an interactive terminal. In a headless run the read-only restriction still applies — the active tool set is rebuilt the same way — but the status pill and notify surface are skipped rather than erroring. And because the on/off state is written into the session as a durable entry, resuming a transcript restores whichever mode you left it in, so a plan-mode session stays read-only across a resume until you explicitly toggle off.