Describe a loop in a file. Run it with one command.
No database, no server, no build step, no dependencies.
npm install -g qloops
The package is qloops; the command it installs is qloop. npm refused the
bare qloop as too close to q-loop, an unrelated package last published in
2016 — so the registry name carries the s and what you type does not.
qloop init release-watch
qloop run release-watch.yaml
Release watch — what shipped in your dependencies · run 819fb995
✓ fetch Fetch releases
✓ llm-call Write the note
✓ api-request Send the note
SUCCESS: Completed 3/3 steps.
That is the whole tool. qloop run executes one pass and exits — see
Scheduling for making it happen every morning.
qloop catalog | the loops that ship with this build |
qloop init <id> [dir] | copy one here, ready to edit |
qloop validate <manifest> | check it and print what it would do |
qloop run <manifest> | execute one pass |
qloop run <manifest> --dry-run | resolve and order every step, touch nothing |
qloop status [<manifest>] | recent runs, and why the last one stopped |
qloop approve <manifest> [runId] | continue a run held at a human gate (--reject refuses) |
qloop doctor | check this machine before blaming the loop |
Exit codes: 0 success · 1 failed · 2 waiting on a human · 64 bad usage.
They differ on purpose — whatever is watching has to tell "it broke" from "there
was nothing today", and both from "somebody needs to look at this".
Installed as qloop. There is deliberately no qf alias: that name belongs to
@q-factory/bridge, and claiming it made npm i -g qloops fail outright — not
partially — for anyone who already had Bridge installed.
One variable covers most of the catalogue:
export OPENROUTER_API_KEY=sk-or-…
Loops that send somewhere need a receiver — a webhook you own, or a Telegram bot:
export QLOOP_WEBHOOK_URL=https://…
export TELEGRAM_BOT_TOKEN=… # from @BotFather
export TELEGRAM_CHAT_ID=…
Without a receiver the loop still runs. The result goes to .qf/out/ and
the run says so, loudly — which is how you prove a loop end to end before you
have credentials for anything. Without a model key it is the other way round:
the step fails rather than inventing text, because invented text would
travel down the chain and out through the next request as if it were real.
qloop doctor tells you which of these is set. It prints names, never values.
Six loops ship with qloop. Each has actually been executed — what
qloop catalog reports is measured from a real run recorded in examples/.
The cheapest one to try: one credential, no accounts anywhere.
qloop init release-watch
Change the URL to a project you actually depend on — GitHub publishes a releases feed for every public repository:
url: "https://github.com/YOUR/REPO/releases.atom"
Reads a feed, writes a short digest, sends it. Runs to the end on its own.
qloop init content-feed
The message carries a signature line with the real cost of that run —
{{run.costUsd}} resolves to what the run has spent by the time the message
goes out. Delete the line if you do not want it.
Searches a news feed and keeps only the mentions actually about you. Says "No mentions today." when there are none, instead of padding.
Point the search at yourself:
url: "https://news.google.com/rss/search?q=YOUR+BRAND&hl=en-US&gl=US&ceid=US:en"
The alternative to one blended summary: fan-out opens a lane per item, so each
entry gets its own model call and its own outgoing message.
Cost scales with items — five lanes is five model calls. That is what the budget knob is for; it cuts before the call that would cross the ceiling.
maxItems: "5" # raise this and raise budgetUsd with it
The shape to copy whenever a loop ends in something you cannot undo:
fetch → agent-gate → human-gate → api-request
The agent-gate is a machine check against your rubric — it decides whether
this is worth anyone's attention. The human gate sits in front of the
irreversible step. Run it and it stops:
⏸ approval-gate Send it?
WAITING_HUMAN: Waiting on a human at step "Send it?".
qloop approve price-watch.yaml # or --reject
Write the rubric as a condition, not a wish. A vague rubric passes everything and is worse than no gate at all.
The same two gates, with publishing at the end. The irreversible step is last and behind both, because a re-run publishes again — there is no idempotency key in the format, and pretending otherwise would be the expensive kind of wrong.
A loop is a YAML file with steps. Six kinds, no more: schedule (a trigger),
fetch, llm-call, api-request, approval-gate, fan-out.
manifest: qf.loop/v1
id: hello
steps:
- id: pull
kind: fetch
config: { url: "https://news.ycombinator.com/rss", format: rss, limit: "5" }
- id: write
kind: llm-call
config:
name: "Write digest"
instructions: "One line per entry: title and link. No preamble."
- id: send
kind: api-request
config:
url: "https://example.com/hook"
body: '{"text":"{{steps.Write digest.output.text}}"}'
qloop validate hello.yaml && qloop run hello.yaml --dry-run
The full schema — every field of every step kind, the three knobs, what is reserved for later — is in SPEC-MANIFEST.md.
Secrets never go in the file: {{env.NAME}} reads them from the environment,
so sharing a loop does not mean sharing your bot.
Everything a run leaves behind sits in .qf/, beside the manifest:
.qf/runs/<runId>.json every step, its output, its tokens, its cost
.qf/last-run.json the newest outcome — status, reason, failing step
.qf/out/<runId>.txt the file sink, when no receiver is configured
Plain files, because the question you actually ask at 09:35 is "what happened",
and cat .qf/last-run.json answers it without a client or a server.
qloop run performs ONE pass. Repetition is launchd's job, where you can see it
in launchctl list and stop it with one command. The template runs daily at
09:30 local time.
sed -e "s#__NODE__#$(command -v node)#" -e "s#__QF__#$(command -v qloop)#" \
-e "s#__MANIFEST__#$PWD/content-feed.yaml#" -e "s#__LOGDIR__#$HOME/Library/Logs#" \
launchd/co.qfactory.content-feed.plist.template > ~/Library/LaunchAgents/co.qfactory.content-feed.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/co.qfactory.content-feed.plist
Stop it with launchctl bootout gui/$(id -u)/co.qfactory.content-feed.
Secrets come from ~/.qf/env, which the job sources before every run — one file
you can chmod 600, never the plist, never the manifest.
If the machine is asleep at 09:30, launchd runs the job on wake. That is the honest limit of a laptop. A digest that must arrive at 09:30 sharp belongs on something that stays awake.
qloop status content-feed.yaml
✗ 2026-08-01 14:53:14 failed "Fetch feed": GET https://… → HTTP 502.
last run FAILED: "Fetch feed": GET https://… → HTTP 502.
A failed run exits non-zero and writes the reason down, so "it broke" and "nothing happened today" never look the same.
Running a loop on your machine is free and always will be — that is this repository. Scheduling as a service, quotas, plans, shared workspaces and the run-history UI are the product.
The line: local execution free, orchestration paid.
Stated plainly, because a tool that implies more than it does costs more than one that admits its edges.
qloop run is one pass. See Scheduling.continue_on_error.sensitivity policy. A manifest that sets one is refused, not run
with the knob ignored — the profile exists to hold back irreversible steps.mode: check is reserved in the format and refused, rather than faked.agent-call. Reserved in the format, not implemented.The same manifests also run inside the product, from a database. Two implementations of one behaviour drift, so they are pinned together by a parity test: one manifest, one loader, executed both ways, step sequence and outcomes compared. A difference is a red test, not a footnote.
MIT.
FAQs
Run a QFactory loop from a YAML manifest. No database, no server, no build step.
We found that qloops demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.
Security News
PHP releases emergency patches for two critical RCE vulnerabilities as agencies urge organizations to take unpatched sites offline.
Threat Research
/Security News
A supply chain attack compromised LiteLLM 1.107.0 on PyPI and Docker, spreading malware that steals cloud credentials, developer secrets, and AI provider keys.