loom-code

The loomflow-native terminal coding agent. Open your project, type what you want, and a loomflow Agent plans, edits, runs, and verifies — with every destructive step gated behind an approval prompt and the model’s entire context visible on demand. loom-code is deliberately thin: the agent loop, tools, planning, and memory are all loomflow. If you’ve read the rest of these docs, you already understand how it works inside.

›  make all the tests in tests/test_parser.py pass

● loom
Two tests were failing on the new date format. I updated parse_date()
to accept ISO-8601 offsets and added a regression case. 8/8 passing.
───────────────────────────── 41,882 in · 1,204 out · $0.0179 · 12% ctx

Source: github.com/Anurich/loomflow-cli  (MIT).

Install

pipx install loom-code

pip install loom-code

pipx install git+https://github.com/Anurich/loomflow-cli

Requires Python 3.11+. Updating later: pipx upgrade loom-code.

Two minutes to first task

cd ~/your-project
loom-code

›  fix the failing test in tests/test_auth.py
›  add a /users endpoint with pagination
›  why is startup slow? profile it

One-shot mode does a task and exits — useful for scripts and CI:

loom-code "add a retry decorator to the http client"
loom-code --yes "scaffold a FastAPI backend"   # skip approvals
loom-code --output-format json "list the modules"   # machine-readable

The interface

loom-code runs a full-screen chat UI: the conversation scrolls in a pane and the input box stays pinned at the bottom, growing as you type. Enter sends, Alt+Enter adds a newline, / pops the command menu. Scroll history with the mouse wheel, PageUp/PageDown, or Ctrl-Up/Down — End jumps back to live. --classic gives you a plain inline prompt instead; piped/non-TTY use falls back automatically.

Steer it while it works

The input box stays live during a turn. Type guidance and press Enter and it’s injected into the running turn before the model’s next step — tagged steering ↳ in the conversation so it reads as guidance, not a queued question:

› run the test suite and fix whatever fails
  ● Run  pytest -q                                    ⏳ working…
› skip the flaky websocket tests, focus on the parser   steering ↳

Press Esc to interrupt the turn entirely — context is kept, so you can redirect with your next message. (Steering rides loomflow’s _loom_steering metadata queue: the ReAct loop drains it before every model call.)

Paste or drop images

Ctrl-V grabs an image straight off your clipboard (screenshots!), and drag-and-drop works too — drop an image file onto the terminal and its path is auto-attached. Either way an [image-N] placeholder lands in the box and the image rides to the model with your next message.

How it thinks

loom-code is a single loomflow Team.supervisor. A read-only coordinator talks to you and delegates writes and shell to a coder worker; specialist sub-agents (explore for read-only investigation, review for independent verification) are invoked as tools when they earn their keep. Every task gets a living plan (loomflow’s plan_write/plan_read — the TodoWrite equivalent), and a StopHook auto-continue loop keeps the agent working until the plan is done, bounded by a configurable cap.

Safety & permissions

The permission layer is the boundary, not the working directory (the Claude-Code model):

• Reads anywhere are allowed; writes outside the project are only possible for files you referenced, and always show a diff prompt — in every mode, even --yes.
• Approval modes (/mode): default asks for writes and shell; accept-edits auto-approves in-project edits; plan is read-only; yolo approves everything except your deny rules.
• “Don’t ask again” is scoped to what you approved: waiving the prompt at a write covers future edits only — bash still asks; at a bash prompt it covers only that leading binary (python … approved once never silences a later rm). The label names the exact scope.
• Rules live in .loom/settings.toml — glob-based allow / ask / deny per tool (e.g. deny = ["edit(*.env)", "bash(rm -rf *)"]). Deny always wins, even in yolo. bash_background shares the exact bash rules.
• Sandbox: --sandbox runs bash under OS-level isolation (writes limited to the repo, network off unless --sandbox-allow-network).
• Irreversible commands (git push --force, rm -rf, …) always get an explicit prompt.

Context you can see

Most harnesses inject content the model reads but you never see, and compact silently. loom-code shows everything:

• /context — the model’s window, tokens used, an occupancy bar, where compaction fires, and every injected working block (repo map, learned notes, project rules, session summary) with its size.
• /prompt — dumps the coordinator’s full system prompt plus every working block, verbatim. Every byte the model reads.
• A N% ctx figure on every turn’s summary line — you always know how close you are to compaction.
• Compaction reports before → after token counts. Never silent.

Recovering & branching

Coding agents don’t win by making fewer mistakes — they win by recovering from them.

• Auto-checkpoints before every edit; /undo restores the working tree; /checkpoints lists them.
• /isolate runs the session in its own git worktree — /review the diff, then /merge or /discard.
• /fork branches the session at the current point (full history inherited, the parent untouched) so you can chase a tangent without polluting the main thread; /tree shows the whole session graph; /resume picks up any prior session.

Staying on track

• Verify-before-done (/verify): a turn that edits code and claims completion without running the project’s tests gets one nudge to run them (the test command is detected, never guessed).
• Loop guard: re-editing one file or re-running a failing command triggers steering to change approach; a command not found gets a PATH/install hint.
• Post-edit diagnostics: after each edit, a cheap per-file syntax/lint check (ruff, node —check, gofmt, bash -n …) surfaces breakage inline, in the same turn.

Gets sharper at your repo

A per-project notebook plus episode memory (.loom/): notes the agent used get credited when a turn goes well, so future runs surface what worked. /good and /bad train it. Research singles out long-term memory as one of the highest-value scaffold components — and it’s built in.

Goal mode

/goal make all tests pass works until the condition is verifiably met (a cheap checker model judges each pass), bounded by a max-pass / no-progress / cost-cap trio. Goals are durable: they persist to .loom/goal.json, so /goal resume continues an unfinished goal even after a restart.

Extend it

Drop files into ~/.loom-code/ (global) or <repo>/.loom/ (project):

• commands/<name>.md — a custom slash command. The body is a prompt template with $1–$9 / $ARGUMENTS; it shows up in /help and autocomplete.
• agents/<name>.md — a custom sub-agent (frontmatter name + description is the delegation contract; the body is its prompt).
• skills/<name>/SKILL.md — an Anthropic-format skill.
• settings.toml — [[hooks]] on eight lifecycle events (PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd, Stop, PreCompact, PostCompact) with background = true fire-and-forget support and updatedInput argument rewriting; [[mcp]] server declarations. Project-scope hooks are trust-gated on first run.

MCP servers connect out of the box — Linear, Sentry, Postgres, Playwright, or any server; /mcp lists what’s live.

Models

Switch anytime with /model <name> or the guided /set_model. Reasoning models support /effort low|medium|high.

Command reference

Type / in the REPL — the menu autocompletes (custom commands included).

Coding

Isolate

Model & tools

Session

CLI flags

Project context

loom-code reads LOOM.md / CLAUDE.md / AGENTS.md / .loom/context.md at the project root and treats it as binding house rules — the same convention as other agent CLIs, so an existing CLAUDE.md works unchanged. /init-loom creates a starter file.

Relationship to loomflow

loom-code is a showcase of the framework as much as a product. The REPL builds one loomflow Agent (a Team with a router, supervisor, and specialists — see Architectures); memory and /resume rehydration are loomflow Memory; the tool kernel is loomflow’s built-in tools behind loom-code’s permission gate. If a capability belongs in the agent loop, it lands in loomflow — the CLI stays thin. Reading its source  is a good way to see loomflow composed in anger.