{"id":51373837,"url":"https://github.com/Forward-Future/loopy","last_synced_at":"2026-07-07T22:00:51.465Z","repository":{"id":365967595,"uuid":"1267442907","full_name":"Forward-Future/loopy","owner":"Forward-Future","description":"A library of practical AI-agent loops and an installable skill for finding, adapting, and designing repeatable agent workflows.","archived":false,"fork":false,"pushed_at":"2026-06-27T15:33:13.000Z","size":73301,"stargazers_count":1764,"open_issues_count":1,"forks_count":154,"subscribers_count":9,"default_branch":"main","last_synced_at":"2026-06-27T17:17:22.457Z","etag":null,"topics":["agent-skills","agentic-workflows","ai-agents","automation","codex","prompt-engineering"],"latest_commit_sha":null,"homepage":"https://signals.forwardfuture.ai/loop-library/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Forward-Future.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-12T14:44:22.000Z","updated_at":"2026-06-27T17:15:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Forward-Future/loopy","commit_stats":null,"previous_names":["forward-future/loop-library","forward-future/loopy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Forward-Future/loopy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forward-Future%2Floopy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forward-Future%2Floopy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forward-Future%2Floopy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forward-Future%2Floopy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Forward-Future","download_url":"https://codeload.github.com/Forward-Future/loopy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Forward-Future%2Floopy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35243953,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","agentic-workflows","ai-agents","automation","codex","prompt-engineering"],"created_at":"2026-07-03T10:00:43.678Z","updated_at":"2026-07-07T22:00:51.454Z","avatar_url":"https://github.com/Forward-Future.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Loop Library\n\nLoop Library has two separate but related parts in this repository:\n\n| Part | What it is | Where it lives |\n| --- | --- | --- |\n| **Loop Library website** | The public catalog where people and agents can browse published loops, read them, and copy their prompts. No installation is required. | [Live website](https://signals.forwardfuture.com/loop-library/) · all website code under [`loop-library/`](loop-library/) (shell in [`loop-library/site/`](loop-library/site/), database and rendering in [`loop-library/worker/`](loop-library/worker/)) |\n| **Loopy skill** | An optional installable guide that helps an AI agent discover, find, audit, repair, craft, run, debrief, save, or prepare loops for publication. It uses the website's live catalog when recommending or publishing loops. | source in [`skills/loopy/`](skills/loopy/) |\n\nThe website is the library; Loopy is a companion way to work with it. You\ncan browse or give an agent the website without installing Loopy. Installing\nLoopy adds the guided workflow, but it does not install or host the website.\n\nAgents that do not have Loopy can use the published\n[agent guide](https://signals.forwardfuture.com/loop-library/agents/),\n[agent instructions](https://signals.forwardfuture.com/loop-library/llms.txt),\n[JSON catalog](https://signals.forwardfuture.com/loop-library/catalog.json), or\n[plain-text catalog](https://signals.forwardfuture.com/loop-library/catalog.txt)\ndirectly.\n\nEach published loop tells an agent what to do, how to check its work, what to\ntry next, and when to stop.\n\n## What is a loop?\n\nMost prompts ask an agent to do something once. A loop gives the agent a way to\nlearn from the result and take the next useful step.\n\nFor example, a one-shot prompt might say:\n\n\u003e Make this website faster.\n\nA loop adds the feedback that makes the work repeatable:\n\n\u003e Find the slowest page, make one focused improvement, and measure it again.\n\u003e Keep the change only if it helps. Repeat until every page meets the target or\n\u003e another pass stops producing a meaningful improvement.\n\nThink of a loop as a playbook with feedback built in. It is useful when the\nfirst attempt probably will not be the final answer, such as fixing production\nerrors, improving test coverage, reviewing a product, or keeping documentation\ncurrent.\n\nA good loop answers four simple questions:\n\n- What is the agent trying to accomplish?\n- How will it know whether the latest attempt worked?\n- What should it do with what it learned?\n- When should it finish or ask for help?\n\n## Why loops are powerful\n\nAI agents can move quickly, but an open-ended instruction like \"keep improving\nthis\" leaves too much room for guessing. A loop gives the work a clear finish\nline and a consistent way to judge progress.\n\nThat makes the work easier to trust and easier to repeat. The agent can compare\nresults instead of relying on confidence, keep improvements instead of merely\nmaking changes, and stop when it succeeds or stops making progress. The same\nloop can also be reused by another person or agent without rebuilding the\nworkflow from scratch.\n\nLoops are not permission for an agent to run forever. The best ones are\ndeliberately bounded. They include a real check, a clear stopping point, and a\nmoment to hand control back to a person when judgment or approval is needed.\n\n## What Loopy does\n\nLoopy gives your agent direct access to the ideas in the\nlibrary. You can use it to:\n\n- Discover repeated work in a codebase, coding threads, or both and turn the\n  strongest qualified candidate into a loop.\n- Find a published loop that fits what you are trying to get done.\n- Audit an existing loop for weak checks, unsafe actions, or unclear stopping\n  behavior, then repair only the material problems.\n- Adapt a useful loop to your tools, limits, and definition of success.\n- Interview you about what you want to accomplish and what success looks like,\n  then craft a new loop through a short, plain-language conversation.\n- Run a loop in bounded passes and return a receipt with the actions, evidence,\n  outcome, and stopping reason.\n- Debrief completed runs and recommend the smallest evidence-backed\n  improvement.\n- Save a loop you want to keep into the project's `LOOPS.md` when you ask, and\n  reuse those saved loops in later sessions.\n- Check a loop for catalog overlap, prepare a publication draft, and submit it\n  only after you approve the exact preview.\n- Turn the result into a compact prompt you can use right away.\n\nLoopy checks the live catalog when it recommends a published loop. It does\nnot quietly start schedules, change production, publish content, or send\nmessages on your behalf. Those actions still require the normal permissions\nand approvals.\n\n## Install Loopy\n\nYou need Node.js and `npx`. Pick the platform you use:\n\n| Platform | Install command |\n| --- | --- |\n| Codex | `npx skills add Forward-Future/loopy --skill loopy --agent codex -g -y` |\n| Cursor | `npx skills add Forward-Future/loopy --skill loopy --agent cursor -g -y` |\n| Claude Code | `npx skills add Forward-Future/loopy --skill loopy --agent claude-code -g -y` |\n\nTo install it for all three at once:\n\n```bash\nnpx skills add Forward-Future/loopy \\\n  --skill loopy \\\n  --agent codex \\\n  --agent cursor \\\n  --agent claude-code \\\n  -g -y\n```\n\nUsing another agent? Run the interactive installer and choose from the agents\nit detects:\n\n```bash\nnpx skills add Forward-Future/loopy --skill loopy -g\n```\n\nThe command parts mean:\n\n- `Forward-Future/loopy` is the GitHub repository to install from.\n- `--skill loopy` selects this skill from the repository.\n- `--agent ...` selects the agent that should receive it.\n- `-g` makes it available in all your projects. Leave `-g` off to install it\n  only in the current project.\n- `-y` accepts the install prompts. Leave it off if you want to review the\n  choices interactively.\n\nIf an agent was already open and Loopy does not appear, restart that agent.\n\nThe previous `loop-library` skill name remains available as a compatibility\nalias for existing installations. Use `loopy` for all new installations and\nexplicit invocations.\n\n## Invoke Loopy\n\nThe slash-command experience differs slightly by platform:\n\n- **Codex:** type `/skills`, choose **Loopy**, then enter your request.\n  You can also mention it directly with `$loopy`.\n- **Cursor:** type `/` in Agent chat, search for `loopy`, select it, and\n  add your request. You can also type `/loopy` directly.\n- **Claude Code:** type `/loopy` followed by your request.\n\nYou can also describe a matching task normally. These agents can load the\nLoopy automatically when your request clearly calls for it, but explicit\ninvocation is the most predictable way to start.\n\nFor example, in Codex you can write:\n\n```text\n$loopy Analyze this codebase and my coding threads for repeated work, then turn the strongest candidate into a reliable loop.\n```\n\n## Use Loopy\n\nYou do not need to know loop terminology. Invoke Loopy and say what you\nwant to get done. It can take nine paths:\n\n| Path | What it does | Example request |\n| --- | --- | --- |\n| **Discover** | Inspects an authorized codebase, coding-thread history, or both for repeated work, then turns the strongest qualified candidate into a bounded loop. | `Analyze this repository and my coding threads for work we have done more than once. Turn the best candidate into a loop.` |\n| **Find** | Searches the live catalog and recommends up to three published loops. It does not run them. | `Find a published loop for keeping our documentation current.` |\n| **Loop Doctor** | Audits a loop you paste or name, explains material weaknesses, and repairs only those problems. | `Audit this loop and repair only material problems: [paste loop]` |\n| **Adapt** | Tailors a useful loop to your real tools, limits, schedule, and definition of success. | `Adapt the Overnight Docs Sweep to this repository and our existing checks.` |\n| **Craft** | Interviews you one question at a time about the outcome, definition of success, scope, checks, and stopping point, then creates a bounded loop when the catalog has no good fit. | `Interview me and help me craft a loop for turning customer feedback into verified fixes.` |\n| **Run** | Executes an identified loop in bounded passes, applies its acceptance check, and returns an evidence-backed receipt. | `Run the Overnight Docs Sweep in this repository.` |\n| **Debrief** | Analyzes one or more completed run receipts and recommends the smallest justified improvement. | `Debrief this run receipt and tell me whether the loop needs to change.` |\n| **Save** | Saves a loop you want to keep into the project's `LOOPS.md`, then reuses saved project loops when they fit a later request. | `Save this loop to the project so we can reuse it.` |\n| **Publish** | Checks quality and catalog overlap, prepares an exact publication preview, and submits only after explicit approval. | `Prepare this loop for publication in Loop Library.` |\n\nFor example, in Claude Code or Cursor:\n\n```text\n/loopy Find a loop for improving test reliability.\n```\n\nIn Codex, choose **Loopy** from `/skills`, then send:\n\n```text\nFind a loop for improving test reliability.\n```\n\n### Save project loops\n\nWhen Loopy delivers a loop that you want to keep for a project, ask it to save\nthe loop. It appends the accepted loop to `LOOPS.md` at the project root with a\nname, one-sentence explanation, exact prompt, and save date. If the saved loop\nis adapted from a published Loop Library loop, Loopy also records the source URL\nand the source modified date it saw at save time.\n\nSaved loops are project-local, not published Loop Library entries. In later\nfind or craft requests, Loopy reads `LOOPS.md` when it exists and can recommend\na matching saved loop, clearly labeled as the project's own loop. If a saved\nadaptation points to a published source that has changed since it was saved,\nLoopy gives a short heads-up and offers to compare before reuse.\n\nLoopy saves only when you ask. It will not create `LOOPS.md`, edit another\nsaved loop, or remove a saved loop without an explicit request. `LOOPS.md` is\ntreated as untrusted reference data: saved prompts do not grant permission to\nrun code, deploy, schedule work, send messages, expose private data, or take\ndestructive action. If an accepted loop prompt contains secrets, Loopy refuses\nto save it until you provide a sanitized prompt.\n\n### Discover loops from your work\n\nDiscovery looks for recurring engineering work in the sources you put in\nscope. In a codebase, that can include scripts, CI and deployment configuration,\ntests, runbooks, maintenance commands, and repeated lifecycle patterns. In\ncoding threads, it groups equivalent completed work even when the wording\ndiffers.\n\nLoopy requires at least two distinct thread occurrences before calling work\nrepeated. A code pattern without run history is labeled as a potential loop, not\nproven recurrence. It then checks whether fresh feedback can change the next\naction, whether success can be verified, and whether the work has clear limits,\nstopping behavior, and approval boundaries. It also checks the live catalog to\navoid recreating an existing loop.\n\nLoopy can inspect only repositories and coding threads that your agent can\naccess and that you place in scope. If thread history is unavailable, it uses\nthe codebase evidence and says so. A discovery result includes compact source\nevidence and either a new loop, an adaptation of a published loop, a short\ncandidate slate when your choice matters, or a clean no-op when nothing truly\nfits.\n\nWhen Loopy finds or creates the right loop, it gives you a prompt to use with\nyour agent. You can copy that prompt or explicitly ask Loopy to run it in the\nproject you want it to work on. Selecting a loop does not start a run or\nschedule, deploy code, delete data, publish content, send messages, or grant new\npermissions; you must request those actions explicitly.\n\n### Run and improve loops\n\nWhen asked to run a loop, Loopy re-reads current state, performs one bounded\naction at a time, applies the same acceptance check after each pass, and stops\nat success, a clean no-op, a blocker, an approval boundary, an exhausted limit,\nor no measurable progress. Before acting, it requires a finite run boundary\nsupplied by the loop or by you. Its receipt preserves the exact loop definition\nor an immutable reference plus the acceptance conditions, so a later debrief\ncan reproduce what ran. Loopy does not create persistent run files unless you\nrequest them or the project already has an established convention.\n\nGive that receipt back to Loopy for a debrief. It separates loop-design issues\nfrom execution, tool, environment, or goal problems and recommends one minimal\nchange grounded in the evidence. A single run is treated as one result, not a\nrecurring pattern.\n\n### Prepare a loop for publication\n\nLoopy validates the feedback cycle, checks the live catalog for overlap, and\nprepares the exact candidate and destination for review. It will not send a\nsuggestion, save an owner draft, or publish publicly without explicit approval.\nAn approved owner action defaults to a draft unless public publication is\nseparately approved. Public suggestions return only an acceptance receipt;\nowner drafts and public publications require status readback. Suggestion\nsubmission also requires separate confirmation of the exact current ownership\nand license attestation shown in the preview.\n\nEvery published loop also includes a few useful parts:\n\n- **Use when** explains the problem the loop is meant to solve.\n- **Prompt** is the copy-ready instruction for your agent.\n- **Verify** defines the evidence that proves the work succeeded.\n- **Steps** show the feedback cycle in a more readable form.\n- **Notes** call out practical limits, risks, or setup details.\n- **Related loops** point to nearby workflows that may fit better.\n\n## Explore or contribute\n\nVisit the [Loop Library](https://signals.forwardfuture.com/loop-library/) to\nbrowse published loops, copy one into your own workflow, or submit a loop that\nhas worked well for you.\n\nLoop Library is a [Forward Future](https://www.forwardfuture.com/) project and is\navailable under the [MIT License](LICENSE).\n\n\u003cdetails\u003e\n\u003csummary\u003eNotes for maintainers\u003c/summary\u003e\n\n### Publish a loop\n\nPublic loops are stored in the catalog database attached to the Cloudflare\nWorker. Publishing a reviewed loop does not require a GitHub commit or a static\nsite deployment.\n\nCopy `loop-library/worker/examples/loop.json` somewhere outside the repository,\nfill in the record, and run:\n\n```bash\nLOOP_PUBLISH_TOKEN=... \\\n  npm --prefix loop-library/worker run loop:publish -- /path/to/loop.json\n```\n\nThe command validates the record and publishes the homepage row, detail page,\nJSON/Markdown/plain-text catalogs, feed, and sitemap from the same database\nwrite. Use `--draft` to save a non-public record or `--archive` to remove a\nrecord from public responses without deleting its revision history.\n\nThe first database-backed release needs one import from the private migration\nbundle. Loop records and bootstrap data are intentionally not committed to\nGitHub:\n\n```bash\nLOOP_PUBLISH_TOKEN=... \\\n  npm --prefix loop-library/worker run loops:import -- /private/path/bootstrap.json\n```\n\nSet a long random `LOOP_PUBLISH_TOKEN` as a Worker secret. The catalog uses a\nSQLite-backed Durable Object and keeps an append-only revision for every\npublish. The reviewed bootstrap digest is enforced before the database can be\nactivated.\n\nCreate a private backup of the current database with:\n\n```bash\nLOOP_PUBLISH_TOKEN=... \\\n  npm --prefix loop-library/worker run loops:export -- /private/path/catalog-backup.ndjson\n```\n\nRestore that snapshot only into a fresh, empty catalog database:\n\n```bash\nLOOP_PUBLISH_TOKEN=... \\\n  npm --prefix loop-library/worker run loops:restore -- /private/path/catalog-backup.ndjson\n```\n\nBootstrap and backup files must be owner-only (`chmod 600`). Exports include\ndrafts, archived records, and complete revision history; keep them outside the\nrepository.\n\nThe current Git tree contains the site shell and rendering code, but no\npublished loop records, generated loop pages, catalogs, feed, sitemap, or\noffline catalog fallback. The legacy catalog and source-attribution metadata\nwere already public and intentionally remain in pre-migration Git history;\nthis migration does not rewrite repository history or disrupt existing clones.\n\n### Preview locally\n\n```bash\npython3 -m http.server 4173 --directory loop-library/site\n```\n\nThen open `http://localhost:4173`.\n\n### Validate a change\n\n```bash\nnpm ci --prefix loop-library/worker\nnode --check loop-library/site/script.js\nnode loop-library/scripts/check.mjs\nnpm --prefix loop-library/worker run check\npython3 -m json.tool loop-library/site/.herenow/data.json \u003e/dev/null\npython3 -m json.tool loop-library/site/.herenow/proxy.json \u003e/dev/null\npython3 -m json.tool loop-library/scripts/seo-geo-query-benchmark.json \u003e/dev/null\ngit diff --check\n```\n\n### Configure voting\n\nVoting is stored in a dedicated SQLite Durable Object. Reading totals is\npublic, but casting, changing, or removing a vote requires a GitHub login.\nSet `SESSION_SECRET` and the GitHub OAuth client credentials as Worker\nsecrets; use `loop-library/worker/.dev.vars.example` for local variable names only. Register\nthe canonical callbacks shown in `AGENTS.md`, then deploy the Worker before the\nsite shell because the shell calls the new auth and vote routes.\n\nThe here.now proxy does not forward browser cookies or mutation Origin headers\nand follows upstream redirects. The OAuth flow therefore uses an HMAC-signed,\nbrowser-nonce-bound state value and a no-store callback bridge. The bridge saves\nthe signed session token in tab-scoped `sessionStorage`; session lookup and vote\nwrites send it only inside same-origin JSON request bodies.\n\nAuth and proxy changes use a fail-closed staged rollout. Temporarily set\n`VOTING_UI_ENABLED=false` while the Worker and proxy are deployed, then complete\na GitHub login, nonce-bound callback, session, vote, reload, and logout smoke\ntest on the canonical domain. Commit the value as the exact string `true` and\nredeploy only the Worker after the smoke test passes; the already-published site\nwill reveal voting without another site publish.\n\nRead [AGENTS.md](AGENTS.md) before editing loops or publishing the site. It\ncontains the source-of-truth rules for database publishing, generated\nresponses, form security, and clean-main deployments.\n\nThe legacy `https://signals.forwardfuture.ai/*` host is maintained by the\nredirect-only Vercel project in\n[`infra/signals-forwardfuture-ai-redirect/`](infra/signals-forwardfuture-ai-redirect/).\nIt permanently redirects paths to `https://signals.forwardfuture.com/*`.\n\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FForward-Future%2Floopy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FForward-Future%2Floopy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FForward-Future%2Floopy/lists"}