the-loop CLI
A lightweight, extensible command-line companion to the-loop — an opinionated product-development-lifecycle harness shipped as a Claude Code and Cursor plugin.
The plugin is the operating model an agent follows inside a session. This CLI is what starts those sessions, keeps them attached to work items, and tells you what happened: a GitHub webhook receiver and a poller that turn ticket activity into agent runs, a session registry, execution control, a structured event log, and repo-scoped commands for the process graph, critic rounds and test-scenario discovery.
Written in Python with one runtime dependency, PyYAML — its whole configuration is YAML, so reading it is not optional — and stdlib otherwise. Python is intentional: it leaves room to add self-learning / ML capabilities later, which are mostly exposed as Python SDKs.
Install
Published to PyPI as the-loopy-one — the base name the-loop was taken. The import
package and the console script keep the natural the_loop / the-loop:
pip install the-loopy-one # PyYAML comes with it — nothing else to add
the-loop --help
From there the CLI installs the rest of the-loop — and upgrades itself:
the-loop install # this CLI + the Claude Code plugin (Cursor: issue #157)
the-loop upgrade # move both to the current release
the-loop install claude --scope project --project-dir . # one repository only
upgrade uses the installer that owns the copy you are running (uv tool, pipx,
pip), and --dry-run prints the exact commands first.
No extras: one pip install the-loopy-one brings everything, including hosting the
control-plane service and its MCP endpoint. ([service], [slack] and [config] are
deprecated no-ops, kept so pinned install lines keep resolving.) Needs Python 3.10+.
In one minute
# 1. Tell the daemon who may drive it, in ~/.the-loop/cli-config.yaml
# routing.authorizedUsers: ["your-github-login"]
# polling.enabled: true # polling needs no inbound networking
# polling.sources: [{ provider: github, repos: ["your-org/your-repo"] }]
# 2. Bring the-loop up: starts every service the config enables — here the
# control-plane service and the poller — detached, logging under .the-loop/logs/.
the-loop start
# 3. Label a GitHub issue "the-loop: auto-execute", then comment:
# the-loop start
# 4. Watch
the-loop status # per-service liveness + the poller's last cycle (exit 0/1)
the-loop sessions list
the-loop events --follow
Or embed it
The package is importable, so the control plane can live inside a Python service you already run instead of a process of its own:
from fastapi import Depends, FastAPI
from the_loop.sdk import TheLoop
loop = TheLoop(config_path="/etc/the-loop/cli-config.yaml")
app = FastAPI()
loop.mount(app, prefix="/the-loop", dependencies=[Depends(verify_caller)])
Same router as the-loop start serves, under your prefix, behind your auth and middleware.
The capabilities work with no HTTP at all (loop.work_items.list()), and
loop.check_environment() says at startup which external binaries your configuration needs.
See the SDK docs.
Documentation
Full docs at https://madarauchiha-314.github.io/the-loop/cli/:
| Overview | What the CLI is, and when you need it |
| Installation | PyPI, uv, extras, what else to have on PATH |
| Getting started | Zero to an auto-executing work item, in five steps |
| Concepts | Ingress, sessions, guards, workspaces, the process graph |
| Commands | gh-webhook · poll · sessions · events · check · graph · critic · scenarios · instructions · install · upgrade · migrate-config |
| Configuration | Every option, by area, with types and defaults |
| Adding a command | The Command / @register contract |
| Python SDK | The same package, imported: mount the control plane into your own FastAPI service, or call the capabilities directly |
Two config files, and they never overlap. The CLI reads
cli-config.yamland nothing else (yours, machine-scoped, resolved via--config→$THE_LOOP_CLI_CONFIG→./.the-loop/cli-config.yaml→~/.the-loop/cli-config.yaml): ingress, routing, the spec directory, the critics, the graph hooks. A repository's.the-loop/harness-config.yamlis the agent's config and is never read by the CLI (issue-352, decision-123). See Configuring the-loop.
Development
the-loop uses uv. From the repository root:
uv sync # install the workspace from uv.lock
uv run the-loop --help
make test # pytest
make check # ruff · pyright · schema validation · pytest
Releases are automatic: on merge to main, cz bump derives the next version from the
Conventional Commits since the last tag and publishes to PyPI via Trusted Publishing
(OIDC — no stored token).
License
MIT.
1 maintainer
Metadata
1 maintainer
Release files for the-loopy-one 18.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| the_loopy_one-18.0.0.tar.gz | 1.3 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| the_loopy_one-18.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.1 MB
Release files / the_loopy_one-18.0.0.tar.gz
| Download URL | the_loopy_one-18.0.0.tar.gz |
|---|---|
| Size | 1.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a4496f4d7ef7fc7727c9b0418efe05dd7f3b307074720a5e7ff39fea1dcdbc7f
|
|
BLAKE2b-256 checksum How to use checksums |
35eab4afc2c4b4f667a31cbb253e805d4b2566f3c39e199626eb02057e93a338
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 15, 2026.
Transparency logRelease files / the_loopy_one-18.0.0-py3-none-any.whl
| Download URL | the_loopy_one-18.0.0-py3-none-any.whl |
|---|---|
| Size | 794.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b7eed894e1ad387087bb391861ec9731ded54c1c584fe92b2b5e56cc5e7f0a9a
|
|
BLAKE2b-256 checksum How to use checksums |
735e74387bad28feb165f98b4dd81a0566b6da96348c6b5b67be05bece2ec3a9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 15, 2026.
Transparency log
