foreloop

The Foreloop CLI. Projects, loops, intentions, stories, and tasks from a terminal — and from anything that can run one, including coding agents and cron.

npm i -g foreloop

Create a key at https://foreloop.com/settings — the Builder preset covers most CLI use.

foreloop auth login              # prompts with the input hidden
foreloop init                    # install the agent skills in this repo
foreloop tasks ready             # open tasks whose contract is approved
foreloop tasks claim             # take one, and print its brief

Let an agent do the work

foreloop init installs six skills written in the Agent Skills open standard, to both places agents look — .agents/skills/ (Codex CLI and others) and .claude/skills/ (Claude Code). Commit them and a teammate gets all three from a fresh clone.

| Skill | What it does | | --- | --- | | foreloop-tasks | Take one approved task and open a pull request for it. | | foreloop-run | Keep watching this repository for new work, on a slow interval. | | foreloop-widget | Install the feedback widget into a site. | | foreloop-cli | Every command and the conventions shared across them, generated from the same table as the commands. | | foreloop-stories | Read a codebase and record what it already does, as Stories. | | foreloop-stories-audit | Check recorded Stories against the code — still true, mis-shaped, or duplicated. |

The names are prefixed deliberately. A skill called run or widget would be claimed for any passing mention of running something or of a widget, hijacking requests that have nothing to do with Foreloop.

After that, any of those agents can watch for approved work and take it on:

> check Foreloop for ready tasks

The skill instructs the executor to claim a task — which the server scopes to this repository — read the brief it prints, branch as <type>/<slug>, say what it is doing at each section break, run the contract's validation, open a pull request ending in Foreloop-Task: <id>, and release the claim with an outcome. It never merges — a human reviews. One task per run.

Claiming needs an API key carrying the task:claim scope. The loop, its lease timing, and its exit codes are in docs/worker-protocol.md.

To watch rather than check once, poll on a slow interval — ten minutes is plenty, since contracts are approved by people:

foreloop tasks ready --json | jq -e '.tasks | length > 0' && run-my-agent

npx foreloop … works without installing, but a global install is the recommendation: this is a tool you reach for many times a day, and npx re-resolves the package on every invocation.

Run foreloop --help for the common path and the output conventions, and foreloop <group> --help to list a group's commands — everyday ones first, one-off maintenance operations after.

Built for scripts and agents

• --json works on any command and has a stable shape. Additive changes only.

• Exit codes are meaningful: 0 ok, 1 failed, 2 auth, 3 usage, 4 confirmation required. A query that finds nothing still exits 0, so callers branch on the payload rather than on failure:

  foreloop tasks ready --json | jq -e '.tasks | length > 0' && run-my-agent

• Unknown commands and flags fail outright rather than guessing at intent.

• FORELOOP_TOKEN outranks any stored credential, so CI needs no login step. FORELOOP_BASE_URL points the CLI at a non-production API.

Also a library

The package re-exports @foreloop/feedback in full, so one dependency covers both the CLI and the feedback widget:

import { initForeloopFeedback } from "foreloop";

await initForeloopFeedback({ apiKey: "slpk_..." });

Embedding the widget and nothing else? @foreloop/feedback alone is smaller and also ships the built browser asset for CDN use. See its README for the script-embed path, configuration, and privacy defaults.