Get started fast.

This is the shortest path from an unconfigured repo to a review-ready PR. Run it from the root of a real repository. Each command writes local files and contacts no server.

# 1. Preview what init will write, then install the harness
npx agentloopkit init --dry-run
npx agentloopkit init

# 2. Give your agent a read-only preflight before it edits
agentloop start --for codex --goal implement --redact-paths

# 3. Scope the work as a contract
agentloop create-task --type bugfix --title "Fix checkout bug" --include-config-commands

# 4. Harden the contract: clear soft spots before you build
agentloop harden

# 5. See the handles an agent can expand, then expand one
agentloop context handles
agentloop context show task:active

# 6. Run the configured checks and capture evidence
agentloop verify --task-commands --progress

# 7. Score review readiness and prepare the PR
agentloop ship
agentloop prepare-pr

Run agentloop start first every session. It reads the evidence the loop already wrote and hands the agent the active task, risk, verification status, the context it can avoid loading, and the next safe command. After you scope the work, run agentloop harden to clear blocking soft spots before building: a thin contract now fails check-gates and blocks ready by default, so hardening early keeps the loop green. context handles then lists what the agent can pull on demand, and context show <handle> expands it back to full local evidence. Finish with ship and prepare-pr so a reviewer gets scored evidence instead of a raw diff.

Six common situations and the commands that fit each one.

I am starting agent work in an existing repo. Install the harness, check setup, then run Start before the agent edits.

npx agentloopkit init
agentloop doctor
agentloop start --for codex --goal implement --redact-paths

I have a thin contract and want it review-safe before building. Report the soft spots, resolve each one, then confirm the gate is clear. create-task already reports soft spots at creation time.

agentloop harden
agentloop harden --resolve <id> --answer "<text>"
agentloop check-gates

I want an autonomous implementation loop with a stop. Create a loop with a runner, a token budget, and a max-iteration cap, then score before each guarded iteration. AgentLoopKit stays controller-only: it scores the next step, runs your configured runner, records the evidence, and decides when to stop.

agentloop loop create \
  --goal "Keep this repo release-ready" \
  --runner-command "npm run check:public-docs" \
  --budget-tokens 50000 \
  --max-iterations 5

agentloop loop scorecard
agentloop loop run
agentloop ready
agentloop loop report

I need the next agent session to continue cheaply. Build a compact context pack and hand over the source handles instead of pasting broad files or chat history.

agentloop context budget
agentloop context pack --for codex --goal continue --redact-paths
agentloop context handles

I need to review an agent-generated PR. Map the diff to evidence, score readiness, then read the maintainer checks.

agentloop explain-diff
agentloop ship
agentloop maintainer-check

I need CI to check review evidence. Run the gates in strict mode inside a pull request workflow (see the GitHub Action section below).

agentloop check-gates --strict

I need MCP-aware agents to request repo context. Start the read-only MCP server. Agents call agentloop_start, agentloop_context_pack, and agentloop_context_show for the same evidence the CLI builds.

agentloop mcp-server

Run AgentLoopKit with npx from the root of the repository you want to configure. init writes files into the current directory, so run it inside the repo, not from your home directory. To keep agentloop and agentloopkit on your PATH, install it globally with npm install -g agentloopkit; both binaries then run without the npx prefix. It also ships as a GHCR container image and in the MCP Registry (see Release channels).

Preview first with --dry-run, then run init. Pin a version for repeatable CI or team setup. Requires Node.js 20 or newer, on macOS, Linux, and Windows.

After init, the recommended first command is agentloop start. It hands an agent a read-only preflight, the active task, current evidence, risk, verification status, and the next safe command, before the agent reads the repo broadly.

A typical session runs the loop end to end, context contract included:

npx agentloopkit init
agentloop start --for codex --goal implement --redact-paths
agentloop create-task --type bugfix --title "Fix checkout bug" --include-config-commands
agentloop context budget
agentloop context pack --for codex --goal continue --redact-paths
agentloop context show task:active
agentloop verify --task-commands --progress
agentloop ship && agentloop prepare-pr

Existing repos can adopt the latest CLI without deleting old harness files. Run doctor to check setup, then upgrade-harness --dry-run to see what the newer CLI would change before it writes anything:

npx --yes agentloopkit@latest doctor
npx --yes agentloopkit@latest upgrade-harness --dry-run
npx --yes agentloopkit@latest ship
npx --yes agentloopkit@latest prepare-pr

init protects existing files. It does not overwrite an edited AGENTS.md, AGENTLOOP.md, or .agentloop/ content; it appends to AGENTS.md and leaves your edits in place.

Per-machine state stays out of git (1.2.0). init writes a .agentloop/.gitignore that keeps machine-specific harness state untracked: state.json (the active-task pointer), loops/<instance>/ directories, and the local runs/ ledger. Durable evidence stays committed: task contracts, reports, handoffs, policies, loops/*.md templates, and manifest.json. The harness's own writes no longer dirty your working tree, where a tool that watches the diff would read them as scope drift. init scaffolds the file skip-if-exists like every other generated file, so your edits to it survive a re-run.

If you committed this state under an older version, re-running init detects the tracked paths and prints the exact git rm -r --cached ... command to un-track them. It uses a :(glob) pathspec, so it targets loop instance directories without touching your tracked loops/*.md templates, and it reports the finding in both human output and --json (as perMachineState). Detection is read-only: init never runs git rm itself.

Because .agentloop/runs/ is now git-ignored, run-ledger files no longer show up as untracked working-tree changes in agentloop status or guard. That is intended, since a local run record is evidence of work already done rather than work still pending.

AgentLoopKit ships a small vocabulary the rest of the page reuses.

• Loop. A controlled run around the active task. agentloop loop create opens it, agentloop loop tick advances it one verified step, agentloop loop status shows where it stands, and agentloop loop report writes a report under .agentloop/loops/. The loop holds the work to the contract instead of running unbounded.
• Runner. The configured command a loop runs. Store it with agentloop loop create --runner-command "..."; agentloop loop run executes one iteration, shell-free, blocking destructive, publish, and git state-changing command families, and records the exit code, bounded output, changed files, a token receipt, and the loop decision. AgentLoopKit stays controller-only: it owns the goal, scope, budget, gates, evidence, stop conditions, and the readiness decision, and it does not become the coding agent.
• Loop scorecard. The read-only decision agentloop loop scorecard returns before another iteration runs: continue, ask-human, stop, or ready, with ranked reasons. It reads the loop contract, readiness gates, scope evidence, runner guardrails, token budget, context handles, and iteration state, and runs nothing. --json returns the same scorecard for tooling.
• Readiness gate. The decisive answer agentloop ready returns from local evidence: ready or not-ready, with the reasons. It reads task clarity, fresh verification, gate compliance, and risk flags, and is meant to run before an agent starts, before a tick advances, and before a task reads complete.
• Token receipt. The four-line summary every loop step prints: 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.
• Start preflight. What agentloop start returns before an agent edits: the active task, a decisive preflight state, read-first source handles, stale or missing verification, risk and scope signals, the next safe command, and a usefulness proof, an impact ledger of the context avoided, broad files avoided, stale proof, and scope drift. Read-only, and it ships over MCP as agentloop_start.
• Harness. The repo-local files init writes: AGENTS.md, AGENTLOOP.md, agentloop.config.json, and .agentloop/ with templates, gates, policies, reports, handoffs, agent instructions, and run evidence.
• Task contract. A scoped Markdown record in .agentloop/tasks/ with the problem, desired outcome, acceptance criteria, non-goals, assumptions, likely files, protected files, verification commands, risk notes, and rollback notes.
• Soft spot. An unresolved weakness in a task contract that agentloop harden detects: a placeholder section, an untestable acceptance criterion, unbounded scope, an unstated assumption, or an acceptance criterion that contradicts a Non-Goal. Blocking soft spots fail check-gates and block ready by default; resolve them with agentloop harden --resolve <id> --answer "...", which records the fix in the contract's ## Hardening Log, or pass --allow-soft-spots to downgrade them to a warning.
• Verification report. Dated Markdown evidence written under .agentloop/reports/ after agentloop verify runs your configured checks: command results, exit codes, and output excerpts. As of 1.1.0, the report records a content-addressed fingerprint of the working tree, so if you edit a file after a passing verify, guard, explain-diff, check-gates, ready, and next report freshness as stale instead of fresh. Freshness is pinned to git content, not timestamps or paths.
• Ship report. A Markdown review-readiness report written by agentloop ship, including evidence, warnings, blockers, next actions, and score details.
• Review-readiness score. A deterministic evidence score from 0 to 100. It scores task clarity, scope control, verification evidence, evidence freshness, gate compliance, handoff readiness, and risk flags. It does not measure code quality.
• PR packet. What agentloop prepare-pr generates: a PR title, body, grouped files, evidence, reviewer checklist, risks, and rollback notes.
• Run ledger. Local evidence folders under .agentloop/runs/ recording ship, verify, and handoff runs.
• File intent. A lookup from local run history that shows which AgentLoopKit runs touched a file and why.
• Gate. A review-evidence check. check-gates considers task evidence, verification evidence, handoff or ship evidence, harness files, policies, git context, and the contract-hardening gate. As of 1.1.0, blocking contract soft spots fail this gate by default (opt out with --allow-soft-spots).
• Maintainer check. A read-only check that helps reviewers decide whether an agent-assisted PR has enough evidence to review.
• Guard. A local pre-flight that bundles drift, proof-debt, stale-verification, baseline, watch-mode, report-writing, and context-budget checks into one agentloop guard run.
• Evidence map. The output of agentloop explain-diff: a deterministic map of whether each changed file is covered by the active task scope, recent run evidence, verification freshness, and risk-sensitive areas.
• Resume pack. A compact continuation brief from agentloop resume-pack, tailored to Codex, Claude, Cursor, a generic agent, or a human reviewer.
• Context budget. A planning estimate of how much context a piece of local evidence carries, so an agent can pass compact evidence instead of broad chat history. agentloop context budget prints transparent context-budget estimates. It is guidance, not a provider tokenizer count or a billing figure.
• Context contract. The agreement the context commands package before broad repo reads: a budget, an evidence map, an auditable pack with a receipt, and reversible source handles. agentloop context budget, agentloop context pack, and agentloop context show build and expand it locally, read-only, with no LLM calls.
• Context pack. What agentloop context pack --for <agent> --goal <goal> writes: a compact continuation pack with a receipt of the included evidence, the broad context it omitted, the source handles, verification freshness, and next actions. Often much smaller than broad file or history context, depending on repo state. Goals cover continue, review, debug, handoff, and research.
• Source handle. A reversible reference inside a pack, such as task:active, verification:latest, run:latest, evidence-map:current, or context-budget:current. agentloop context handles lists which handles are available and how to expand each one, and agentloop context show <handle> expands one back to the full local evidence, so a pack traces back to the repo. Each handle carries a digest, so agentloop context show --since <digest> returns an unchanged receipt when the underlying evidence has not moved, and the next worker can trust a cached handle instead of re-expanding it.
• Policy. A local Markdown safety file for a risk category (destructive actions, secrets, dependencies, public APIs, database, UI, security review).

agentloop start is the repo-native preflight a software agent runs before it touches code. It reads the local evidence the loop already wrote and hands back current repo truth: the active task, a decisive preflight state, read-first source handles, stale or missing verification, risk and scope signals, the next safe command, and the estimated context the agent can avoid loading. Pass --for to tune the briefing for an agent (codex, claude, cursor, opencode, gemini, copilot, or generic) and --goal for the work at hand, such as implement or continue. --redact-paths masks file paths for shareable logs.

Start resolves to a clear state, ready continuation, missing task, missing or stale verification, scope drift, review-ready work, blocked risk, or an evidence-only session, so the agent acts on the state and the next safe command instead of guessing. It also records a usefulness proof, an impact ledger of the context avoided, broad files avoided, stale proof and scope drift caught, source handles offered, and verification freshness, so the value of the preflight is measurable. Those numbers are local planning estimates, not provider billing figures. It is read-only and local-first: no provider proxy, no hidden prompt rewriting, no .env reads, and nothing published, tagged, or mutated.

Start pairs with the Context Contract commands. agentloop context handles lists every source handle the briefing offers, its availability, and the command to pull it; agentloop context budget measures context pressure; agentloop context pack builds an auditable continuation pack with a receipt; and agentloop context show task:active expands a source handle back to full local evidence. The same briefing ships over MCP as agentloop_start, so an agent platform can request it without broad repo scans.

The loop commands are the control plane around a task. agentloop loop create opens a controlled loop on 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/. Each step holds the work to the contract instead of letting an agent run unbounded, and each step prints a token receipt.

agentloop loop scorecard is read-only. It checks the loop contract, readiness gates, scope evidence, runner guardrails, token budget, context handles, and iteration state. It returns one decision: continue, ask-human, stop, or ready. Run it before another iteration so the loop spends budget only when the next step is worth it. agentloop loop scorecard --json returns the same scorecard for tooling, and --id <id> scores a specific loop instead of the newest one.

agentloop loop scorecard
agentloop loop scorecard --json

agentloop loop run is the guarded runner. Store a runner on the loop contract with agentloop loop create --runner-command "...", then agentloop loop run executes one iteration of that command. Execution is shell-free and blocks destructive, publish, and git state-changing command families, and each iteration records the exit code, bounded output, changed files, a token receipt, and the loop decision. AgentLoopKit stays controller-only: it owns the goal, scope, context budget, verification gates, evidence, stop conditions, and the readiness decision, and it does not become the coding agent. With a token budget and a max-iteration cap, a loop runs autonomous implementation iterations on compact context that stop on their own.

The token receipt has four lines: the estimated broad context a naive session would carry, 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.

agentloop ready is the readiness gate. It reads local evidence (task clarity, fresh verification, gate compliance, and risk flags) and returns a decisive ready or not-ready answer with reasons. Run it before an agent starts, before a tick advances, and before a task reads complete. As of 1.1.0, blocking contract soft spots block ready by default, so a thin or unbounded contract reads not-ready until you run agentloop harden; pass --allow-soft-spots to downgrade that to a warning.

An autonomous loop with a stop scores, runs a guarded step, checks readiness, and reports:

agentloop loop create \
  --goal "Keep this repo release-ready" \
  --runner-command "npm run check:public-docs" \
  --budget-tokens 50000 \
  --max-iterations 5
agentloop loop scorecard
agentloop loop run
agentloop ready
agentloop loop report

The Context Contract is the layer an agent meets before it reads your repo broadly. It runs locally and read-only: it builds a budget, maps the evidence, writes an auditable pack with a receipt, and hands back reversible source handles. The source truth stays in the repo, and no command calls an LLM, proxies a provider, or intercepts a prompt.

Your software agent / app
  (Codex, Claude Code, Cursor, OpenCode, Gemini CLI, Copilot CLI,
   LangChain, Agno, Strands, your own scripts...)
        |
        | task contracts - diffs - verification - runs - research notes - logs
        v
 +-----------------------------------------------------------------------+
 | AgentLoop Context Contract  (runs locally; source truth stays in repo) |
 |-----------------------------------------------------------------------|
 | Context Budget  ->  Evidence Map  ->  Pack Receipt  ->  Source Handles |
 |                                      |                                 |
 |                                      +-- task:active                   |
 |                                      +-- verification:latest           |
 |                                      +-- run:latest                    |
 |                                      +-- evidence-map:current          |
 |                                      +-- context-budget:current        |
 |                                                                       |
 | Goals: continue - review - debug - handoff - research                  |
 | MCP tools - generated agent instructions - transparent heuristics      |
 +-----------------------------------------------------------------------+
        |
        | compact context pack + retrieval handles
        v
Agent session / review / research handoff

agentloop context budget measures context pressure with transparent estimates. agentloop context pack --for codex --goal continue --redact-paths builds the pack and its receipt, often much smaller than broad file or history context, depending on repo state. agentloop context handles lists every handle the pack offers, its availability, and the command to pull it, and agentloop context show task:active expands a source handle back to full local evidence. Each handle carries a digest, so agentloop context show --since <digest> returns an unchanged receipt when the evidence has not moved, and the next worker can trust a cached handle instead of re-expanding it. Goals cover continue, review, debug, handoff, and research. Generated agent guidance tells Codex, Claude Code, Cursor, OpenCode, Gemini CLI, GitHub Copilot CLI, and generic agents to request a context pack before broad repo reads, and the same tools ship over MCP as agentloop_context_budget, agentloop_context_pack, and agentloop_context_show.

Write a contract before a coding session so the agent has a boundary instead of guessing at scope. create-task records the problem, desired outcome, acceptance criteria, non-goals, assumptions, likely files, protected files, verification commands, risk notes, and rollback notes.

Pass --json to get the created path and Markdown back for an agent. task list, task show, task set, and task status manage contracts without mutating files you did not name. Status values are proposed, in-progress, blocked, deferred, review, and done. Status is not verification evidence: run agentloop verify before claiming completion.

agentloop harden is a front-of-loop pass that interrogates a task contract for unresolved soft spots before implementation starts, so you fix a thin contract early instead of at review. Detection is deterministic and LLM-free: AgentLoopKit finds and structures the soft spots, and the agent or author answers them.

It reports five soft-spot types:

• Placeholder sections. Template text left unfilled, including an empty Files or Areas Not to Touch section.
• Untestable acceptance criteria. Criteria a verification command could not decide.
• Unbounded scope. Scope with no boundary a reviewer could hold you to.
• Unstated assumptions. Assumptions the contract relies on but never records.
• Acceptance vs Non-Goals contradictions. An acceptance criterion that conflicts with a stated Non-Goal.

Run agentloop harden [task] to report the soft spots for a contract (the active task when you omit [task]). Record a resolution with --resolve <id> --answer "<text>"; AgentLoopKit writes the answer into the correct contract section and logs it under a ## Hardening Log heading. Soft-spot ids are stable across resolutions, so a batch of --resolve calls is safe. A resolution that does not clear the soft spot is rejected, so the log records real fixes, not acknowledgements.

# Report the soft spots in the active contract
agentloop harden

# Resolve one by id
agentloop harden --resolve scope-1 --answer "Limited to src/auth/**; no changes to the session store."

Hardening sits at the front of the loop. agentloop create-task reports soft spots by default at creation time, and when the active contract has blocking soft spots, the next-action guidance in agentloop next, start, and status (and the MCP nextAction field) recommends agentloop harden before verify, handoff, or ship. init also writes .agentloop/harden-playbook.md with agent-facing guidance for the hardening loop.

AgentLoopKit controls the work between ProjScan and AgentFlight: ProjScan finds the risk, AgentLoopKit defines scope, acceptance criteria, and verification gates, and AgentFlight proves the result. The three tools stay separate, connect through local versioned JSON under .baseframe/, and the integration is opt-in.

Create a task from a ProjScan assessment. Run ProjScan with --emit-baseframe, then hand its assessment to create-task.

projscan assess \
  --intent "Implement password reset" \
  --task-id auth-password-reset-20260626-01 \
  --emit-baseframe

agentloopkit create-task \
  --from-projscan .baseframe/evidence/auth-password-reset-20260626-01/projscan-assessment.json

AgentLoopKit reads the assessment and writes a native task plus a machine-readable task contract at .baseframe/evidence/<task-id>/agentloopkit-task.json, and it creates or updates .baseframe/agent-workflow.json.

Override the inferred fields. The assessment seeds the task; pass flags to set the title, allowed paths, and acceptance criteria explicitly.

agentloopkit create-task \
  --from-projscan .baseframe/evidence/auth-password-reset-20260626-01/projscan-assessment.json \
  --title "Implement password reset" \
  --allow "src/auth/**" \
  --allow "tests/auth/**" \
  --acceptance "Reset tokens expire" \
  --acceptance "Reset tokens cannot be reused"

Output layout. Each tool owns one artifact under the shared task id.

.baseframe/
  agent-workflow.json
  evidence/
    <task-id>/
      projscan-assessment.json
      agentloopkit-task.json
      agentflight-result.json

• AgentLoopKit consumes projscan-assessment.json.
• AgentLoopKit owns agentloopkit-task.json.
• AgentFlight later writes and consumes agentflight-result.json.
• The contract AgentFlight should consume is .baseframe/evidence/<task-id>/agentloopkit-task.json.

Caution. A ProjScan assessment provides assessment evidence, not complete acceptance criteria. If acceptance criteria cannot be inferred safely, AgentLoopKit writes placeholder criteria and requires a human to complete them before the task reads ready.

Reconcile AgentFlight results. After AgentFlight records execution proof, reconcile it against the required gates.

agentloopkit check-gates \
  --task auth-password-reset-20260626-01 \
  --from-agentflight .baseframe/evidence/auth-password-reset-20260626-01/agentflight-result.json

• Required gates are matched by verification command.
• Passed, failed, missing, and incomplete verification are each surfaced.
• Scope drift and proof gaps are surfaced.
• AgentLoopKit does not mark a task complete automatically when required gates fail or are missing.

This is a read-side check: AgentLoopKit reads AgentFlight's result artifact to reconcile gates. It does not require AgentFlight for standalone use, and it never writes AgentFlight's artifact.

agentloop verify reads agentloop.config.json, runs the configured commands, captures output excerpts, and writes a dated Markdown report under .agentloop/reports/. Pass --task to fold the task title, type, and status into the report.

As of 1.1.0, the report records a content-addressed fingerprint of the working tree (a local hash that excludes AgentLoopKit's own generated evidence). guard, explain-diff, check-gates, ready, and next compare that fingerprint against the current tree, so an edit made after a passing verify is reported as stale rather than fresh. Freshness is pinned to git content, not timestamps, so a check can never read false-green on code that changed after it passed.

It does not hide failures. A failed report lists each failed command with its exit code and final useful output, and truncated logs keep their first and last lines so the error stays visible. AgentLoopKit does not read .env files or print arbitrary environment variables.

verify --post-verification-gates runs verification first, then checks the gates against the evidence it just produced, so you get a verification report and a gate result from one command.

ship checks the active task, changed files, verification freshness, gates, handoff evidence, and risk flags. It writes a Markdown ship report under .agentloop/reports/, records a local run under .agentloop/runs/, and calculates an explainable review-readiness score.

The score does not measure code quality. It measures whether the work has enough local evidence for a reviewer to inspect it.

As of 1.1.0, the ship report lists which verification commands were skipped in a Verification Not Run section, matching prepare-pr and handoff, so a reviewer reading the ship report alone can tell whether lint, typecheck, and build actually ran. Blocking contract soft spots fail ship by default; pass --allow-soft-spots to downgrade them to a warning.

agentloop guard is a quick local pre-flight before review. In one pass it checks scope drift between the active task and the working tree, proof debt where changed files have no evidence, stale verification, baselines, watch-mode awareness, report writing, and context-budget pressure. It reads what the loop already wrote: it does not run tests, call external APIs, or change task state.

agentloop guard --json --compact returns the same checks as a small structured payload: bounded finding-path lists, compact evidence maps, and source-handle expansion guidance instead of a broad changed-file dump, so an agent can read the result without loading the whole tree. --write-report writes the guard result as a local report, --write-baseline records a baseline to compare future runs against, and --redact-paths masks file paths for public logs. Run guard mid-session for a quick read on where the change stands, then run ship when you want a scored, recorded review-readiness report.

The context-budget figure guard prints is a transparent character-count heuristic for planning. It is not a provider tokenizer count or a billing claim.

agentloop explain-diff prints a deterministic evidence map for the current diff. For each changed file it shows whether the change is covered by the active task scope, backed by recent run evidence, supported by fresh verification, and whether it touches risk-sensitive areas. It is a read-only analysis of your working tree against local evidence, with no tests run and no task state changed.

Use it to answer "is this change accounted for?" before you ship or hand off. --redact-paths masks file paths for public logs and PR comments.

agentloop resume-pack packages the local evidence into a compact continuation brief for the next worker, whether that is another agent or a human. Pass --for to tailor the brief: codex, claude, cursor, generic, or human. Each brief carries context-budget estimates so the next worker can load compact local evidence instead of broad chat history or a long changed-file list.

The estimates use a transparent character-count heuristic for planning, not provider tokenizer counts or billing claims. --redact-paths masks file paths for public logs.

prepare-pr generates a PR title and body from the active task, changed files, verification evidence, ship report, gates, risk notes, and rollback notes. It groups changed files by review area and can print GitHub-comment Markdown for CI.

The packet reconciles promise against evidence. Each acceptance criterion is cross-referenced against the verification report and labeled proven (a linked verification command passed), failing (a linked command failed), not run (the linked command is absent or there is no report yet), or unlinked (no (verified by: <keys>) tag, so there is no local proof and the reviewer judges it). Link a criterion to the commands that prove it by ending the line with, for example, (verified by: test, typecheck). The Evidence Map section then lists the changed files not tied to task intent (unexplained by task scope, or in the forbidden-file scope) with their explanations, and says so plainly when every change is accounted for. The reviewer reads intent against change, not just a diff.

AgentLoopKit does not read GitHub tokens, call GitHub APIs, or post comments by itself.

AgentLoopKit records local evidence under .agentloop/runs/. A run can include a task reference, changed files, a verification report reference, a ship report, score JSON, a PR summary, diff stats, and metadata.

intent <file> uses local run metadata only. It shows which previous AgentLoopKit runs touched or referenced a file and why.

maintainer-check helps maintainers review agent-assisted PRs. It checks for task evidence, fresh verification evidence, handoff or ship evidence, changed file count, dependency and lockfile changes, migrations, auth or security-sensitive files, and generated output files.

When you import local GitHub issue and PR metadata into .agentloop/github/context.json, that context can surface in review-context, prepare-pr, and maintainer-check. The import is explicit and local: no tokens, no API calls, and no env-file reads.

It is read-only. It does not run tests, write reports, call GitHub, read tokens, or upload files.

For projects that adopt AgentLoopKit as a dev dependency, maintainers can add their own local maintenance script that runs the same evidence checks before release. In AgentLoopKit's own repo a maintenance gate handles this, but you do not need that internal script to use the product.

check-gates checks review evidence without running tests: task evidence, verification evidence, handoff or ship evidence, harness files, policies, git context, and the contract-hardening gate. Use it for a quick pass/fail signal.

Soft spots fail by default (1.1.0). Blocking contract soft spots now fail check-gates and block ready by default. Before 1.1.0 they only warned and failed under --strict. A contract with untestable acceptance criteria, unbounded scope, or an unfilled Files or Areas Not to Touch section no longer passes the gate: run agentloop harden to resolve the soft spots. Upgrading from 1.0 makes these commands newly red on un-hardened contracts, which is intended, a stronger trust gate.

Opt out with --allow-soft-spots. Pass --allow-soft-spots to downgrade a blocking contract-hardening soft spot back to a warning. The flag is accepted by check-gates, ready, ship, badge, and ci-summary, and as the allowSoftSpots argument on the MCP agentloop_check_gates tool, so every review surface has the same opt-out. It does not disable the other gates.

Use ship when you want a scored review-readiness report and a run ledger entry. check-gates stays the lightweight evidence gate.

agentloop handoff writes a deterministic reviewer summary from git status, diff stats, the active task contract, and the latest verification report, grouping changed files into review areas. Like prepare-pr, it reconciles each acceptance criterion against the verification report (proven, failing, not run, or unlinked) and lists the changed files not tied to task intent, plus any verification commands that were skipped. report writes a local static HTML evidence page, release-notes drafts notes from local evidence, and badge writes an SVG status badge (pass --allow-soft-spots to badge --source gates to downgrade a blocking soft spot to a warning). None of these publish, tag, or upload anything.

agentloop release-proof checks post-release evidence for the local package version across npm, GitHub Releases, GHCR, and the MCP Registry, without publishing, tagging, uploading, or reading tokens. Use it after a release to confirm the published evidence matches the local version.

Handoff remains useful when you want a deterministic reviewer summary without the full ship score. For most agent-generated changes, run ship first and prepare-pr before opening a PR.

agentloop install-agent writes repo-specific instructions for the software agent you use, or for all supported agents at once. AgentLoopKit writes safe repo-local Markdown when a third-party config convention is uncertain, rather than editing tool config it cannot verify.

Supported agents: Codex, Claude Code, Cursor, OpenCode, Gemini CLI, and GitHub Copilot CLI.

agentloop mcp-server exposes existing repo evidence to MCP clients over a read-only local stdio server. It provides tools for status, next action, task contracts, active task, policies, latest verification report, latest ship report, artifact inventory, review context, run ledger summaries and details, file intent, maintainer checks, gate status, and handoff summaries.

Start ships over MCP as agentloop_start, so an agent platform requests the same preflight briefing the CLI returns without broad repo scans. The Context Contract ships over MCP too: agentloop_context_budget returns the context-budget estimate, agentloop_context_pack builds the auditable pack with its receipt, and agentloop_context_show expands a source handle back to full local evidence. An agent platform consumes the same contract the CLI builds.

The server does not run verification commands, edit files, call external APIs, read .env contents, upload data, or mutate repository files.

AgentLoopKit ships a GitHub Action so the same review-readiness checks can run in CI. Use it to run maintainer-check, ship --github-comment, prepare-pr --github-comment, or check-gates --strict in pull request workflows. The CLI does not read GitHub tokens or post comments by itself. If a workflow posts a PR comment, use normal GitHub Actions permissions and pass only static, trusted command strings.

name: AgentLoopKit

on:
  pull_request:

jobs:
  agentloop:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 20
      - uses: abhiyoheswaran1/AgentLoopKit@v1.1.0
        with:
          command: "maintainer-check --redact-paths"

Do not pass untrusted pull request text, issue titles, commit messages, or user-controlled input into the Action command.

AgentLoopKit publishes through several channels, each carrying the same versioned build:

• npm / npx. The primary install path: npm install -g agentloopkit, or run it with npx agentloopkit init.
• GitHub Releases. Tagged releases with notes for each version.
• GHCR image (Docker). A container image for pipelines that want a pinned runtime.
• MCP Registry metadata. Discovery metadata for the read-only MCP server.
• GitHub Action. The CI surface shown above.

1.1.0 is the latest release: npm (agentloopkit@1.1.0, the latest tag, published with SLSA provenance), the GitHub Release (v1.1.0), the GHCR image (1.1.0), and the MCP Registry entry (agentloopkit@1.1.0) are live. Each GitHub Release publishes the release asset with a SHA-256 checksum so you can verify a download, and npm's provenance attestation ties the published package to the source and build. Pin the repository release ref for the GitHub Action, uses: abhiyoheswaran1/AgentLoopKit@v1.1.0; a GitHub Marketplace listing is a separate owner-side publication step, so pin the release ref rather than resolving through the Marketplace.

Since 1.0, the entire shipped surface is a committed public contract across six axes (CLI commands and flags, the agentloop.config.json schema, the MCP tool surface, --json output shapes, exit codes, and the generated harness format), under a SemVer promise: no breaking change to any committed surface within 1.x.

After a release, agentloop release-proof checks that npm, GitHub Releases, GHCR, and the MCP Registry all carry the local package version, without publishing, tagging, or reading tokens.

A quick map from the moment you are in to the command that fits. The section below explains each command in the order the loop usually runs them.

Situation	Run
New repo setup	agentloop doctor, then agentloop start
Thin or un-hardened contract	agentloop harden
Driving a controlled loop	agentloop loop create, then agentloop loop tick
Before another loop iteration	agentloop loop scorecard
Autonomous loop with a stop	agentloop loop create --runner-command "...", then agentloop loop scorecard, then agentloop loop run
Is this ready to proceed	agentloop ready
Agent about to edit	agentloop start
Need compact context	agentloop context pack
Need exact source truth	agentloop context show <handle>
Dirty repo, unsure of scope	agentloop guard
Before a PR	agentloop verify, agentloop ship, agentloop prepare-pr
Reviewing agent work	agentloop maintainer-check

Reach for the command that matches the moment in the loop:

• doctor: check setup and warnings before you start.
• loop create / loop tick / loop status / loop report: open a controlled loop, advance it one verified step, see where it stands, and write a loop report.
• loop scorecard: score whether the loop can continue, should stop, needs a human, or is ready, before another iteration spends budget. Read-only, with ranked reasons; --json for tooling.
• loop run: execute one configured runner iteration, shell-free and guarded, recording exit code, output, changed files, a token receipt, and the loop decision.
• ready: get a decisive ready or not-ready answer before an agent starts, before a tick advances, or before completion.
• start: get a read-only preflight before an agent edits, with the active task, state, risk, verification, and the next safe command.
• create-task: define the work before editing.
• harden: interrogate a contract for soft spots and record resolutions before implementation.
• context budget: measure context pressure before broad reads.
• context pack: build an auditable continuation pack with a receipt.
• context show: expand a source handle back to full local evidence.
• verify: capture test, build, and lint evidence.
• guard: a fast pre-flight for drift, proof debt, stale verification, and context-budget pressure.
• explain-diff: map changed files to task scope, run evidence, verification freshness, and risk areas.
• ship: decide whether the change is review-ready.
• prepare-pr: generate the PR body.
• resume-pack: hand the next agent or reviewer a compact continuation brief.
• maintainer-check: help reviewers inspect agent-assisted work.
• runs: inspect local evidence history.
• intent: explain why a file changed across prior runs.
• upgrade-harness: inspect old generated guidance without overwriting it.
• release-proof: verify public release evidence after publishing.

Common snags and the fix for each.

• "No active task" from Start or Context. Nothing is pinned, so the briefing has nothing to anchor to. Create one with agentloop create-task --type bugfix --title "...", or pin an existing contract with agentloop task set .agentloop/tasks/<file>.md.
• Stale verification. The latest report is older than your current changes. Re-run agentloop verify --task-commands, then agentloop ship to score against fresh evidence.
• Context too large. A pack or briefing is heavier than you want. Run agentloop context budget to see the pressure, then agentloop context pack to omit broad changed-file detail and hand over source handles instead. Expand only what you need with agentloop context show <handle>.
• Marketplace listing not found. A GitHub Marketplace listing is a separate owner-side publication step. Pin the release ref directly, uses: abhiyoheswaran1/AgentLoopKit@v1.1.0, instead of resolving through the Marketplace.
• npx resolves an old install. A local or global agentloopkit can shadow the latest. Force the current release with npx --yes agentloopkit@latest <command>, or check what resolves with npx agentloopkit --version.
• Generated harness is old. If doctor flags missing Start or context guidance, preview an upgrade with agentloop upgrade-harness --dry-run, then run agentloop upgrade-harness to apply it. It does not overwrite your edits.

AgentLoopKit is intentionally boring.

• No postinstall script. npm install agentloopkit runs no AgentLoopKit code.
• No telemetry, no cloud backend, no database, no API key, and no hidden network calls.
• No provider proxy and no hidden prompt rewriting. AgentLoopKit does not sit between your agent and a model provider, and it does not rewrite or intercept prompts. Commands are local and explicit.
• No .env content reading: verify, ship, the run ledger, and the MCP server do not read .env contents or print arbitrary environment variables.
• Repo-local files only. AgentLoopKit does not edit your repository's root .gitignore, global Git config, or shell profiles. Since 1.2.0 init writes one .agentloop/.gitignore, scoped to its own directory, so the harness's per-machine state stays untracked.
• ship, prepare-pr, maintainer-check, review-context, and mcp-server are read-only unless a command explicitly writes a local AgentLoopKit report or run record.
• Verification commands run only when you explicitly run verify or pass a flag such as ship --run-verify.
• GitHub-comment output is Markdown only. AgentLoopKit does not post comments by itself, and --redact-paths is available for public logs and PR comments.
• init --dry-run previews every change before anything is written, and init appends to an existing AGENTS.md instead of overwriting it.