agentloopkit weekly downloads statistics

AgentLoopKit

<p align="center"> <img src="https://raw.githubusercontent.com/abhiyoheswaran1/AgentLoopKit/main/docs/logo/icon.svg" alt="AgentLoopKit logo" width="96" height="96"> </p>

A drop-in engineering loop for software agents.

An open-source Baseframe Labs developer tool.

Your software agent can produce a diff. AgentLoopKit helps you decide whether that work is reviewable, verifiable, and merge-ready.

It gives Codex, Claude Code, Cursor, OpenCode, Gemini CLI, GitHub Copilot CLI, and other engineering agents a local acceptance layer: task contracts, safety rules, verification evidence, review-readiness scores, PR descriptions, and reviewer handoffs.

Unstructured automation produces code. Agentic engineering produces auditable work.

ProjScan finds the risk. AgentLoopKit controls the work. AgentFlight proves the result.

<p align="center"> <img src="https://raw.githubusercontent.com/abhiyoheswaran1/AgentLoopKit/main/docs/assets/readme/agentloopkit-showcase.png" alt="AgentLoopKit workflow showing task contracts, verification reports, and handoff artifacts" width="100%"> </p>

The screenshots and terminal demos in this README are generated from committed sources in docs/assets/readme/ with Playwright and VHS. You can regenerate them locally.

What It Does

AgentLoopKit is a repo-level toolkit for developers using Codex, Claude Code, Cursor, OpenCode, Gemini CLI, GitHub Copilot CLI, and other engineering agents.

Keep your agent, IDE, and CLI. AgentLoopKit gives those tools a repeatable local workflow:

1. Specify the task.
2. Constrain the risk.
3. Implement the smallest useful change.
4. Verify with real commands.
5. Review the diff.
6. Hand off with evidence.
7. Ship only when the work is reviewable.

Run init inside an existing repository and AgentLoopKit creates:

• .agentloop/ for tasks, reports, handoffs, gates, policies, templates, and agent instructions
• AGENTS.md for agent-facing repo guidance
• AGENTLOOP.md for the working loop
• agentloop.config.json for local command and path settings

Generated AGENTS.md includes a specialist roster for product, CLI, template, verification, security, release, docs, compatibility, MCP, and repo-steward work. It helps future agent sessions split work without adding a background service.

<p align="center"> <img src="https://raw.githubusercontent.com/abhiyoheswaran1/AgentLoopKit/main/docs/assets/readme/agentloopkit-cli.gif" alt="Terminal demo showing AgentLoopKit init, task creation, verification, ship evidence, PR preparation, review context, run history, and file intent" width="100%"> </p>

The CLI demo shows the normal path: initialize a repo, create a task, run reviewed verification, score review readiness, draft PR copy, inspect review context, and trace why a file changed.

Install

Use it with npx from the repository you want to configure:

cd /path/to/your/repo
npx agentloopkit init --dry-run
npx agentloopkit init

init writes files into the current directory. --dry-run previews the same plan and writes nothing.

Commit the generated harness baseline before your first feature task when you want clean diff evidence. If the harness files are still uncommitted, explain-diff, Guard, and resume packs will include those generated files as local work, which is accurate but noisier than the steady-state loop.

After setup, non-init commands search upward for the nearest agentloop.config.json and use that folder as the AgentLoop root. You can run agentloop status, agentloop verify, agentloop ship, or agentloop prepare-pr from a nested source folder and still write tasks, reports, runs, and handoffs to the initialized repo root.

Do not run init from your home directory unless you intend to configure your home folder. AgentLoopKit refuses that by default; --force allows it and prints a home-directory target warning. If you want local agent guidance but do not want to commit the generated files, use local-only mode:

npx agentloopkit init --local-only

--local-only writes the harness, asks Git for this clone's metadata directory, then adds a marked block to that clone's info/exclude for .agentloop/, AGENTS.md, AGENTLOOP.md, and agentloop.config.json. It does not edit .gitignore, global Git config, shell profiles, or other project files.

The examples below use agentloop after setup. If you are not installing the package locally or exposing its binary on PATH, keep using the one-off form, for example npx --yes agentloopkit@latest doctor --redact-paths.

Check the published package explicitly:

npx --yes agentloopkit@latest version
npx --yes agentloopkit@latest init

For repeatable CI or team setup, replace @latest with a vetted version.

Before initialization, exploratory preflight can be advisory:

npx --yes agentloopkit@latest doctor --advisory --redact-paths

Advisory mode keeps missing-setup diagnostics visible but exits 0 so first-run scripts can continue. Use plain doctor or doctor --strict for gates that should fail on setup errors.

Pinned team usage:

pnpm add -D agentloopkit
pnpm agentloop init

Existing Repos

Repos that already use AgentLoopKit can update the CLI without rewriting local harness files:

cd /path/to/existing/repo
npx --yes agentloopkit@latest version
npx --yes agentloopkit@latest doctor --redact-paths
npx --yes agentloopkit@latest upgrade-harness --details --redact-paths
npx --yes agentloopkit@latest init --dry-run

These commands inspect the published package. This repository may document unreleased guidance before the next publish; check release status before expecting agentloopkit@latest to include new subcommands.…