AgentLoopKit

# 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 coding agents.

An open-source Baseframe Labs developer tool.

Your coding agent can write code. AgentLoopKit helps you decide whether that code is reviewable, verifiable, and merge-ready.

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

Vibe coding produces code. Agentic engineering produces auditable work.

<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 demo in this README are generated from committed sources in `docs/assets/readme/` with Playwright and VHS.

## What It Does

AgentLoopKit is a repo-level toolkit for developers using Codex, Claude Code, Cursor, OpenCode, Gemini CLI, GitHub Copilot CLI, and other coding 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.

## Install

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

```bash
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.

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`, or `agentloop handoff` from a nested source folder and still write tasks, reports, and handoffs to the initialized repo root.

Do not run `init` from your home directory unless you intend to configure your home folder. If you want local agent guidance but do not want to commit the generated files, use local-only mode:

```bash
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.

Check the published package explicitly:

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

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

Pinned team usage:

```bash
pnpm add -D agentloopkit
pnpm agentloop init
```

## Core Workflow

```bash
npx agentloopkit init
agentloop create-task --title "Fix login redirect bug" --type bugfix \
  --acceptance "Password-reset login redirects to the requested page" \
  --include-config-commands \
  --verification "npm test -- auth"

# Run Codex, Claude Code, Cursor, OpenCode, Gemini CLI, or another coding agent.

agentloop verify --task .agentloop/tasks/<task-file>.md --task-commands --only-task-commands --progress
agentloop ship --github-comment
agentloop prepare-pr
```

`create-task` sets the new contract as the active task. Use `agentloop task set <path>` only when you need to switch to another contract.
Add `--include-config-commands` when you want the task contract to copy non-empty `test`, `lint`, `typecheck`, and `build` commands from `agentloop.config.json`. Task creation records those commands; it does not run them. Use `verify --only-task-commands` when the contract already includes the full check list.
After verification and handoff, use `agentloop task done` to close the active task before starting unrelated work.

Use `agentloop status` or `agentloop next` when an agent needs the next local action without reading every file:

```bash
npx agentloopkit status
npx agentloopkit status --brief
npx agentloopkit next
```

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

The terminal demo is generated from committed VHS sources in this repository.

## Dogfood Gate

AgentLoopKit uses its own loop in this repo. Contributors can run the same local self-check:

```bash
npm run dogfood
```

That command checks task-folder hygiene, current loop status, public docs hygiene, review gates, artifact inventory, maintainer reviewability, agent review context, and ProjScan health. It does not publish packages, create tags, post comments, read tokens, read `.env` contents, or run verification commands.

Run the public-doc check by itself when you edit README, examples, or release-channel docs:

```bash
npm run check:public-docs
```

Use the stricter gate before a release or final handoff:

```bash
npm run dogfood:strict
```

## Commands

The package exposes two binaries:

```bash
agentloop init
agentloopkit init
```

| Command                          | Purpose                                                                        |
| -------------------------------- | ------------------------------------------------------------------------------ |
| `agentloop init`                 | Generate the repo harness and config                                           |
| `agentloop doctor`               | Check setup health, commands, git state, and risk files                        |
| `agentloop create-task`          | Create a scoped task contract                                                  |
| `agentloop task ...`             | List, show, pin, update, archive, and inspect task state                       |
| `agentloop status`               | Show active task, latest report, latest run, dirty files, and next step        |
| `agentloop next`                 | Print only the next recommended loop action                                    |
| `agentloop review-context`       | Show one read-only reviewability context snapshot                              |
| `agentloop verify`               | Run configured checks and write a verification report                          |
| `agentloop ship`                 | Score review readiness, write a ship report, and optionally print a PR comment |
| `agentloop prepare-pr`           | Generate a PR title, grouped body, and optional GitHub comment                 |
| `agentloop summarize`            | Preview a deterministic reviewer summary                                       |
| `agentloop handoff`              | Write a reviewer handoff summary                                               |
| `agentloop check-gates`          | Check review evidence without running tests                                    |
| `agentloop runs --latest`        | Show the newest local ship, verify, or handoff run entry                       |
| `agentloop show-run <id>`        | Show one local run ledger entry                                                |
| `agentloop intent <file>`        | Show which runs touched a file and why                                         |
| `agentloop maintainer-check`     | Check whether an AI-assisted PR is reviewable                                  |
| `agentloop artifacts`            | Inventory local task, report, handoff, and badge evidence                      |
| `agentloop report`               | Write a local static HTML evidence report                                      |
| `agentloop badge`                | Write a local SVG evidence badge                                               |
| `agentloop ci-summary`           | Summarize CI context and existing AgentLoop evidence                           |
| `agentloop release-notes`        | Draft local release notes from repo evidence                                   |
| `agentloop release-check`        | Check local release readiness without publishing                               |
| `agentloop npm-status`           | Check npm registry status without publishing                                   |
| `agentloop mcp-server`           | Start the read-only MCP stdio server                                           |
| `agentloop policy ...`           | Read and compare local safety policies                                         |
| `agentloop install-agent <name>` | Add agent-specific instructions                                                |
| `agentloop list-templates`       | List bundled templates                                                         |
| `agentloop completion <shell>`   | Print shell completion scripts                                                 |
| `agentloop version`              | Print the CLI version                                                          |

Clean up finished task contracts after verification and handoff:

```bash
agentloop task archive --status done --dry-run
agentloop task archive --status done
```

See [docs/cli-reference.md](docs/cli-reference.