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 <handle>. 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 <handle-from-start> --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 <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 --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