AgentLoopKit

Features

What it does well.

See it in action

A closer look.

What's new in 1.2.0

Loops stop dirtying your working tree.

1.2.0: init now keeps per-machine harness state out of git automatically, so loops and run ledgers never show up as working-tree drift. Under it, 1.1.0's reviewer trust holds across the whole loop. A reviewer can approve or reject an agent's work from local evidence alone, in a single pass, without re-deriving what the agent did. AgentLoopKit hardens a task contract before you build, pins freshness to git content so a check can never read false-green, puts each acceptance criterion next to the verification command that proves it, and makes the trust gates fail by default. Everything stays deterministic and LLM-free, and runs on your machine. ProjScan finds the risk, AgentLoopKit controls the work, AgentFlight proves the result.

Per-machine state stays out of git

init writes a .agentloop/.gitignore that keeps machine-specific state untracked: the active-task pointer, loop instance directories, and the local run ledger. Durable evidence stays committed. The harness's own writes no longer dirty your working tree, where a tool that watches the diff would read them as scope drift. Re-run init on a repo that committed this state under an older version and it prints the exact git rm -r --cached ... command to un-track it, without ever running git rm itself.

Harden the contract before you build

agentloop harden interrogates a task contract for unresolved soft spots (placeholder sections, untestable acceptance criteria, unbounded scope, unstated assumptions, and contradictions with Non-Goals) before implementation starts, so you fix a thin contract at the front of the loop instead of at review. Deterministic and LLM-free.

No false-green checks

Fresh, covered, and verified are now pinned to git content hashes, not timestamps or file paths. Edit a file after a passing verification and its freshness reads stale, so a stale edit can never slip through as verified.

Promise vs. evidence, side by side

The PR and handoff packet shows which acceptance criteria are proven by a passing verification command, and which changed files are not tied to task intent. The reviewer reads intent against change, not just a diff.

Gates that bite by default

Blocking soft spots now fail check-gates and block ready by default (opt out with --allow-soft-spots), ship reports which verification commands were skipped, and create-task surfaces soft spots at creation time.

Hardened before release

1.1.0 shipped after a two-round adversarial hardening pass: several correctness and security fixes, each landed with a regression test. Every release publishes to npm with SLSA provenance, and also ships to GHCR and the MCP Registry.See the changes on GitHub

Loop controls

Drive the whole loop from one local control plane.

AgentLoopKit is the local control plane for low-token, verifiable agent loops. Loop controls drive the work step by step, a decisive readiness gate calls whether work can proceed, and a token receipt prints on every step. It owns the middle of the Baseframe loop: task scope, acceptance criteria, verification gates, and completion decisions. Everything runs locally and read-only where it reads.

Drive the loop

agentloop loop create opens a controlled loop around the active task, agentloop loop tick advances it one verified step, agentloop loop status shows where it stands, and agentloop loop report writes a loop report under .agentloop/loops/. The loop holds the work to the contract instead of letting an agent run unbounded.

Readiness gate

agentloop ready returns a decisive ready or not-ready answer from local evidence: task clarity, fresh verification, gate compliance, and risk flags. Use it before an agent starts, before a tick advances, and before a task reads complete.

Token receipts

Every loop step prints a token receipt with four lines: the estimated broad context, the compact context AgentLoopKit hands over instead, AgentLoopKit's own overhead, and the net context reduction. The figures are transparent local planning estimates, not provider tokenizer counts or billing claims.

Unchanged receipts

Context handles carry a digest, so agentloop context show --since <digest> reports an unchanged receipt when the underlying evidence has not moved. The next worker can trust a cached handle instead of re-expanding it.

Owns the decision

AgentLoopKit decides when work is in scope, verified, and done. ProjScan and AgentFlight hand it evidence; the completion decision stays here, recorded in local files you can read.

Baseframe Suite v1

Baseframe Suite Integration.

ProjScan finds the risk, AgentLoopKit controls the work, and AgentFlight proves the result. The suite connects the three through local versioned JSON under .baseframe/: AgentLoopKit imports a ProjScan assessment, owns the machine-readable task contract, updates the workflow manifest, and reconciles AgentFlight verification against the required gates. The tools stay separate and local-first; nothing merges.

Import a ProjScan assessment

agentloop create-task --from-projscan .baseframe/evidence/<task-id>/projscan-assessment.json reads ProjScan's repository assessment and writes a native AgentLoopKit task with scope, acceptance criteria, and verification gates.

Own scope, gates, and the decision

AgentLoopKit emits .baseframe/evidence/<task-id>/agentloopkit-task.json, a machine-readable task contract for AgentFlight, and updates .baseframe/agent-workflow.json. It owns task scope, acceptance criteria, verification gates, and completion decisions; ProjScan and AgentFlight each own their own artifact.

Reconcile AgentFlight later

agentloopkit check-gates --task <task-id> --from-agentflight .baseframe/evidence/<task-id>/agentflight-result.json matches AgentFlight's recorded proof to the required gates by verification command, surfacing passed, failed, missing, and incomplete results, plus scope drift and proof gaps. A task never reads complete while a required gate fails or is missing.

Assessment evidence, not acceptance criteria

A ProjScan assessment carries risk, not finished acceptance criteria. When AgentLoopKit cannot infer criteria safely, it writes placeholder criteria and holds readiness until a human completes them.

Still fully standalone

The integration is opt-in. create-task, verify, ship, prepare-pr, check-gates, Start, the Context Contract, MCP, and the GitHub Action all work without ProjScan or AgentFlight. No cloud backend, no telemetry, no LLM required.

Start here

One command, current repo truth before the first edit.

Run agentloop start --for codex --goal implement --redact-paths and an agent gets a compact, read-only briefing in place of a broad repo scan.

Read first

The active task and current work, the evidence map, and the latest verification, so the agent starts from what the repo already knows.

Do not broad-scan

A compact briefing with local source handles, so the agent loads broad files only when it needs them.

Risk

Stale proof, scope drift, and risky files when present, surfaced before the first edit rather than after review.

Impact

An estimate of the context avoided. It is a local planning signal, not a provider billing figure.

Next command

A single next safe command, usually agentloop context show <handle> to expand a source handle back to full local evidence.

Context Contract

The AgentLoop Context Contract.

Before an agent starts work, AgentLoopKit packages the exact local evidence it needs, why it matters, what was omitted, and how to expand the source truth. The context commands run locally and read-only, call no LLM, and leave the source truth in your repo.

Measure context pressure

agentloop context budget reports transparent context-budget estimates for the local evidence in play, so an agent sees the pressure before it pastes broad file or history context. The estimates are character-count heuristics for planning, not provider tokenizer counts or billing claims.

Build an auditable pack

agentloop context pack --for codex --goal continue --redact-paths writes a continuation pack with a receipt: the included evidence, the broad context it omitted, the source handles, verification freshness, and the next actions. A pack is often much smaller than broad file or history context, depending on repo state. Goals cover continue, review, debug, handoff, and research.

Expand the source truth

agentloop context show task:active expands a reversible local source handle back to its full evidence. Handles cover task:active, verification:latest, run:latest, evidence-map:current, and context-budget:current, so a reviewer can trace a pack back to the repo.

Same tools over MCP

The read-only MCP server exposes agentloop_context_budget, agentloop_context_pack, and agentloop_context_show, so an agent platform consumes the same context contract directly. No LLM calls, no provider proxy, no prompt interception, no telemetry.

Workflow

From request to review-ready PR.

One loop runs from a plain request to a PR a reviewer can trust. Each step is a command you hand to the next agent or maintainer.

Specify the task

Turn a request into a scoped contract before the first edit. npx agentloopkit create-task --type bugfix --title "Fix checkout bug"

Let your agent implement

Use Codex, Claude Code, Cursor, OpenCode, Gemini CLI, Copilot CLI, or another software agent inside the repo. AgentLoopKit does not replace your agent. It holds the work to the contract.

Verify evidence

Run the repo's configured checks and capture the result as a dated report. npx agentloopkit verify

Ship the review packet

Score review readiness from evidence and write a ship report. npx agentloopkit ship

Prepare the PR

Generate a PR title, body, grouped files, evidence, and a reviewer checklist. npx agentloopkit prepare-pr

Help maintainers review

Evaluate an agent-assisted PR against task evidence, fresh verification, and risky areas. npx agentloopkit maintainer-check

Trust

Local-first, and intentionally boring.

AgentLoopKit only writes transparent repo files, and only when you run a command. Nothing runs on install, and nothing leaves the machine.

No install scripts, no telemetry

No postinstall script, no telemetry, no cloud backend, no database, no API key, and no hidden network calls. npm install agentloopkit runs no AgentLoopKit code.

Commands run only when you invoke them

Nothing happens in the background. Each command does one thing when you run it, writes repo-local files, and contacts no server.

Repo-local files only

AgentLoopKit writes inside the current repository: AGENTS.md, AGENTLOOP.md, agentloop.config.json, and .agentloop/. It does not touch your root .gitignore, global Git config, or shell profiles. The one .gitignore it writes lives inside .agentloop/ and covers only its own per-machine state.

Never reads your secrets

verify, ship, the run ledger, and the MCP server do not read .env contents or print arbitrary environment variables. They read what the loop already wrote.