Get started fast.

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.

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.

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

• Harness. The repo-local files init writes: AGENTS.md, AGENTLOOP.md, agentloop.config.json, and .agentloop/ with templates, gates, policies, reports, handoffs, and agent instructions.
• Task contract. A scoped Markdown file in .agentloop/tasks/ recording the problem, outcome, constraints, non-goals, assumptions, likely files, forbidden files, acceptance criteria, verification commands, and rollback notes.
• Verification report. What agentloop verify writes after running your configured checks: command results, exit codes, and output excerpts under .agentloop/reports/.
• Gate. A review-evidence check. check-gates confirms a contract, verification report, handoff, harness files, and core policies exist before you claim the work is done.
• Handoff. A deterministic reviewer summary built from git state, the active contract, and the latest verification report.
• Policy. A local Markdown safety file for a risk category (destructive actions, secrets, dependencies, public APIs, database, UI, security review).

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, likely files, forbidden files, acceptance criteria, verification commands, 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, review, and done. Status is not verification evidence: run agentloop verify before claiming completion.

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

It does not hide failures. A failed report lists each failed command with its exit code and final useful output before the full log, and truncated logs keep their first and last lines so the error stays visible. In GitHub Actions, the report records the workflow, event, ref, commit, and run URL; local reports stay quiet. AgentLoopKit does not read .env files or print arbitrary environment variables.

agentloop check-gates checks for the evidence a reviewer expects without running tests or calling an LLM: a task contract, a verification report, a handoff summary, harness files, core safety policies, and git context.

Warnings keep exit code 0 by default. Use --strict in pull-request CI when a warning gate should fail the command. doctor checks setup health; check-gates checks whether the current session carries review evidence.

agentloop handoff writes a reviewer-ready summary from deterministic inputs: git status, diff stats, the active task contract, the latest verification report, and config settings. It groups changed files into review areas (source, tests, docs, CI, config, AgentLoop artifacts, and risk-sensitive paths) and adds review-focus hints from file paths. It does not call an LLM.

agentloop report writes a local static HTML evidence page from the same inputs. agentloop release-notes drafts release notes from local changelog, git, task, and verification evidence. agentloop badge writes an SVG status badge. None of these publish, tag, or upload anything.

agentloop install-agent writes repo-specific instructions for the coding 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, the active task, policies, the latest verification report, and handoff summaries.

The server does not run verification commands, edit files, call external APIs, read .env contents, or upload data. It reads what the loop already wrote and serves it to an MCP-aware client.

AgentLoopKit is intentionally boring, and that is the point.

• No postinstall scripts. npm install agentloopkit runs no AgentLoopKit code.
• No telemetry, no cloud backend, no database, no API key requirement, and no hidden network calls.
• init --dry-run previews every change before anything is written, and init appends to an existing AGENTS.md instead of overwriting it.
• init --local-only writes the harness and excludes it from the current clone through .git/info/exclude, without editing .gitignore, global Git config, or shell profiles.
• Completion scripts print to stdout; AgentLoopKit does not edit .zshrc, .bashrc, fish config, or PowerShell startup files.
• verify, status, and the MCP server do not read .env contents or print arbitrary environment variables.