Agentloopkit

AgentLoopKit

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.

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.

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.

init skips existing generated files and appends to unmarked AGENTS.md files instead of overwriting maintainer edits. Use upgrade-harness to find older guidance that does not tell agents to run agentloop doctor and agentloop start before broad reads, list handles with agentloop context handles when available, or expand source truth with agentloop context show . Copy only the useful pieces into AGENTS.md, AGENTLOOP.md, or .agentloop/harness/*.

You can use the latest loop before refreshing old guidance:

npx --yes agentloopkit@latest create-task --type bugfix --title "Fix checkout bug"

npx --yes agentloopkit@latest start --for generic --goal implement --redact-paths npx --yes agentloopkit@latest verify npx --yes agentloopkit@latest ship npx --yes agentloopkit@latest prepare-pr npx --yes agentloopkit@latest maintainer-check

Core Workflow

First useful loop after init:

agentloop doctor

agentloop create-task --type bugfix --title "Fix checkout bug" --include-config-commands agentloop status --brief agentloop start --for codex --goal implement --redact-paths agentloop loop create --goal "Keep checkout work release-ready" --budget-tokens 50000 --max-iterations 5 agentloop loop tick agentloop loop scorecard agentloop ready agentloop verify --task-commands --progress agentloop ship agentloop prepare-pr agentloop task done

That sequence creates a task contract, checks the repo setup, gives the next software agent a compact start briefing, records a local loop contract with token receipts, scores whether another loop pass should continue, checks readiness gates, runs only reviewed verification commands, records review-readiness evidence, drafts PR copy, and closes the active task. It does not post to GitHub, publish packages, call an LLM, execute a coding agent, or run hidden commands.

Make Your Agent Start Here

Before a software agent broad-scans the repo, run:

agentloop doctor --redact-paths

agentloop start --for codex --goal implement --redact-paths agentloop context handles --redact-paths agentloop context show --redact-paths

doctor checks the Agent Readiness Matrix: Doctor-before-Start guidance, Start guidance, context-handle guidance, broad-read avoidance, MCP guidance, and installed agent instruction files. start gives the current task, proof, risk, context budget, and source handles. context handles lists which handles are available now. context show expands exact local source truth only when the agent needs detail.

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 software agent.

agentloop verify --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 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 --task-commands --only-task-commands when the active contract already includes the full check list. Use verify --post-verification-gates only for reviewed task gates that need the verification report to exist first. After verification and ship, use agentloop prepare-pr for reviewer copy and 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:

npx agentloopkit status

npx agentloopkit status --brief npx agentloopkit next npx agentloopkit next --redact-paths

When status or next recommends create-task in a dirty repo, the reason calls out existing dirty non-evidence files so agents can confirm the next task scope before implementation. When create-task sees that same pre-existing dirty work, it also adds a bounded Risk Notes bullet to the generated task contract so later review evidence preserves the baseline count and examples.

Use agentloop start --for codex --goal implement --redact-paths when a software agent needs the repo truth before broad reads. Start is the preflight: current task when one exists, decisive state, next safe command, read-first handles, risk summary, verification freshness, context-budget impact, and source handles. Use agentloop context handles to list available handles and normal empty states, then agentloop context show to expand source truth only when needed. Use agentloop context pack --for codex --goal continue --redact-paths when you need the lower-level receipt and omission details directly. Use agentloop guard when you want a live local check for scope drift, stale verification, proof debt, and context-budget pressure before review. Use agentloop explain-diff when you need to understand whether the current changed files are covered by task scope, recent run evidence, fresh verification, and risk guidance. Use agentloop resume-pack --for codex, --for claude, --for cursor, --for generic, or --for human when you need the older compact continuation surface. These commands are read-only by default and use local evidence only.

agentloop start is the agent starting point. It keeps agents from guessing by turning task state, changed files, verification, risk, and context pressure into one compact preflight. The Context Contract sits underneath it: context pack explains why each item is present, names what was left out, and provides local handles for the source truth. A large changed-file list becomes a small briefing the agent can expand only when it needs detail.

agentloop loop adds a local loop contract on top of normal task contracts. agentloop loop create records the goal, budget, stop conditions, suggested commands, native task path, and a token receipt.