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 daemon reads
cli-config.yaml(yours, machine-scoped, resolved via--config→$THE_LOOP_CLI_CONFIG→./.the-loop/cli-config.yaml→~/.the-loop/cli-config.yaml). A repository's.the-loop/harness-config.yamlis the plugin config and is never read by the daemon — includingauthorizedUsersand a poll source'srepos, which have no fallback and fail closed when unset. 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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file the_loopy_one-13.6.0.tar.gz.
File metadata
- Download URL: the_loopy_one-13.6.0.tar.gz
- Upload date:
- Size: 1.1 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4c8a2b144285455c6c025a398fdec1f00bce095daa36fa590515f1b8377ebe5e
|
|
| MD5 |
650b7c321376df07ee397a8fe5fd438b
|
|
| BLAKE2b-256 |
a3353ff1900c831534cc5b0b7ec9d19c5c83a0df0091a473e9ab3e1ec4c61ea2
|
Provenance
The following attestation bundles were made for the_loopy_one-13.6.0.tar.gz:
Publisher:
release.yml on MadaraUchiha-314/the-loop
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
the_loopy_one-13.6.0.tar.gz -
Subject digest:
4c8a2b144285455c6c025a398fdec1f00bce095daa36fa590515f1b8377ebe5e - Sigstore transparency entry: 2765222071
- Sigstore integration time:
-
Permalink:
MadaraUchiha-314/the-loop@4e118f24004314e82859c05bfc9d89bfb2c3840d -
Branch / Tag:
refs/heads/main - Owner: https://github.com/MadaraUchiha-314
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@4e118f24004314e82859c05bfc9d89bfb2c3840d -
Trigger Event:
push
-
Statement type:
File details
Details for the file the_loopy_one-13.6.0-py3-none-any.whl.
File metadata
- Download URL: the_loopy_one-13.6.0-py3-none-any.whl
- Upload date:
- Size: 695.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4090bd17ffd556ead685b7589179b5c9cdca42904b3366753fcca391f4a9aba5
|
|
| MD5 |
25f75bc194c66a68d2990841f00d325a
|
|
| BLAKE2b-256 |
20b86c557e64e50bf62131cc103f7f625d1bde928ac7cada8095c51cbde9700a
|
Provenance
The following attestation bundles were made for the_loopy_one-13.6.0-py3-none-any.whl:
Publisher:
release.yml on MadaraUchiha-314/the-loop
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
the_loopy_one-13.6.0-py3-none-any.whl -
Subject digest:
4090bd17ffd556ead685b7589179b5c9cdca42904b3366753fcca391f4a9aba5 - Sigstore transparency entry: 2765222081
- Sigstore integration time:
-
Permalink:
MadaraUchiha-314/the-loop@4e118f24004314e82859c05bfc9d89bfb2c3840d -
Branch / Tag:
refs/heads/main - Owner: https://github.com/MadaraUchiha-314
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@4e118f24004314e82859c05bfc9d89bfb2c3840d -
Trigger Event:
push
-
Statement type:
