AgentLoopKit MCP server
✓ VerifiedProvides a local engineering loop for software agents to manage task contracts, verification, and review-readiness scores.
Also known as abhiyoheswaran1/AgentLoopKit
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.2.0
- Last commit
- Jul 14, 2026
- License
- MIT
What is AgentLoopKit MCP?
AgentLoopKit provides a local engineering loop for software agents to manage task contracts, verification, and review-readiness scores.
Summary generated from the project's README
About AgentLoopKit MCP server
AgentLoopKit provides a local engineering loop designed for developers using software agents like Claude Code, Cursor, Codex, and GitHub Copilot CLI. It acts as an acceptance layer that transforms unstructured automation into auditable engineering work by managing task contracts, safety rules, and verification evidence. The toolkit is used locally within a repository to ensure that agent-generated code is reviewable and merge-ready through a repeatable workflow.
Users initialize the environment using npx agentloopkit init, which generates essential files such as AGENTS.md for repo guidance and a .agentloop directory for managing tasks and reports. The system includes specialized tools like agentloop verify to run reviewed commands, agentloop ship to record evidence, and agentloop prepare-pr to draft pull request descriptions. It helps developers control the work of agents by providing review-readiness scores and managing context budgets to prevent scope drift.
What you can do with it
- 1Establish task contractsA developer can define a specific bugfix task with clear acceptance criteria and verification commands for an agent to follow.
- 2Verify agent implementationYou can run specific, reviewed commands to ensure the agent's changes meet the required technical standards.
- 3Prepare pull request documentationThe tool can automatically draft the necessary text and context for a pull request after the work is verified.
- 4Manage agent context efficiencyDevelopers can provide agents with compact briefings that include risk summaries and source handles instead of allowing broad repository scans.
Written from the project's README. Every use case is checked against a quote from it.
How to install AgentLoopKit MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall AgentLoopKit MCP in Claude Code
$ claude mcp add agentloopkit -- npx -y agentloopkitInstall AgentLoopKit MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"agentloopkit": {
"command": "npx",
"args": [
"-y",
"agentloopkit"
]
}
}
}Install AgentLoopKit MCP in VS Code
.vscode/mcp.json
{
"servers": {
"agentloopkit": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"agentloopkit"
]
}
}
}Install AgentLoopKit MCP in VS Code CLI
$ code --add-mcp '{"name":"agentloopkit","type":"stdio","command":"npx","args":["-y","agentloopkit"]}'Install AgentLoopKit MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"agentloopkit": {
"command": "npx",
"args": [
"-y",
"agentloopkit"
]
}
}
}Install AgentLoopKit MCP in Codex
$ codex mcp add agentloopkit -- npx -y agentloopkitInstall AgentLoopKit MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.agentloopkit] command = "npx" args = ["-y", "agentloopkit"]
Install AgentLoopKit MCP in Gemini CLI
$ gemini mcp add -s user agentloopkit npx -- -y agentloopkitInstall AgentLoopKit MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"agentloopkit": {
"command": "npx",
"args": [
"-y",
"agentloopkit"
]
}
}
}Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableabhiyoheswaran1/agentloopkit is public and reachablegithub.com/abhiyoheswaran1/agentloopkit ↗Pass
- Package names this repository as its sourceagentloopkit names abhiyoheswaran1/agentloopkit as sourcenpmjs.com/package/agentloopkit ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for agentloopkitnpmjs.com/package/agentloopkit/v/1.2.0#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-07-14github.com/abhiyoheswaran1/agentloopkit ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from agentloopkitPass
- No critical advisory in the package or its dependencies120 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubAgentLoopKit
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:
- Specify the task.
- Constrain the risk.
- Implement the smallest useful change.
- Verify with real commands.
- Review the diff.
- Hand off with evidence.
- 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 instructionsAGENTS.mdfor agent-facing repo guidanceAGENTLOOP.mdfor the working loopagentloop.config.jsonfor 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
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 <handle> 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. agentloop loop tick records one iteration decision from local evidence: continue, stop, ask for human review, or mark the loop ready when gates pass. Once a loop asks for human review, AgentLoopKit rejects another tick until someone reviews the loop report and resolves the blocking evidence. Use agentloop ready when you need the current review-readiness gate summary without creating a loop.
Use agentloop harden [task] before work starts to interrogate a task contract for unresolved soft spots — placeholder text, unbounded scope, unstated assumptions, untestable acceptance criteria, and contradictions between Acceptance Criteria and Non-Goals. It defaults to the active task and exits non-zero when a blocking soft spot remains. Resolve one with agentloop harden --resolve <id> --answer "...", which records the answer in the contract's Hardening Log. agentloop create-task reports the same soft spots by default right after creating a contract.
For a bounded autonomous pass, configure one local runner command and let AgentLoopKit record the iteration:
agentloop loop create \
--goal "Keep checkout work release-ready" \
--runner-command "node scripts/agentloop-runner.mjs" \
--runner-timeout-ms 600000 \
--budget-tokens 50000 \
--max-iterations 5
agentloop loop run
agentloop loop scorecard
agentloop ready --strict
agentloop loop report
loop scorecard is the pre-flight gate before another autonomous pass. It reads the loop contract, readiness state, context pack, token budget, iteration budget, runner guardrails, and scope evidence, then returns continue, ask-human, stop, or ready. It does not execute the runner or run verification.
loop run executes only the command saved in the loop contract. It uses shell: false, rejects shell syntax, blocks publish and destructive command families, caps runner output, records changed files, and still applies the max-iteration and token-budget stop conditions. AgentLoopKit controls the goal, budget, scope, gates, evidence, and stop decision. Your agent, script, CI job, or AgentFlight session does the implementation work.
JSON and MCP context budget/pack payloads keep that boundary: they include compact evidence fields and the evidence-map:current handle, but they do not send the full changed-file list unless the agent expands that local handle.
Start uses a strict current-work rule. It accepts active or open task contracts. Archived, done, deferred, and AgentFlight placeholder tasks stay as previous evidence. Start and Context omit task:active handles and agentloop ship guidance for old work. In a clean repo with only previous evidence, Start tells the agent that no active task exists.
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 Start Preflight + Context Contract (source truth stays here) |
|------------------------------------------------------------------------|
| State -> Next Safe Command -> Read First -> Risk -> Impact -> Handles |
| | |
| +-- task:active (current work only)|
| +-- verification:latest |
| +-- run:latest |
| +-- evidence-map:current |
| +-- context-budget:current |
| |
| Goals: implement - continue - review - debug - handoff - research |
| MCP tools - generated agent instructions - transparent local heuristics |
+------------------------------------------------------------------------+
|
| compact preflight + retrieval handles
v
Agent session / review / research handoff
The context-budget example is generated from local AgentLoopKit output in this repository. Token estimates use ceil(character_count / 4) for planning, not provider tokenizer counts or billing claims. The percentage changes with repo state; the point is that agents can start from selected evidence and expand source handles instead of pasting broad history.
Run the repeatable Start usefulness demo to create a temporary messy repo and see agentloop doctor check agent-readiness guidance, then agentloop start report context avoided, broad files avoided, stale proof, scope drift, source handles, and the next safe command.
The terminal demo is generated from committed VHS sources in this repository. It shows the intended agent workflow: check readiness with Doctor, run Start preflight, see what not to broad-scan, expand the current task handle when one exists, and verify with local evidence.
Verification reports turn local commands into review evidence. They keep command status, failure summaries, task links, changed-file context, and follow-up gates in one artifact reviewers can inspect.
Dogfood Gate
AgentLoopKit uses its own loop in this repo. Contributors can run the same local self-check:
npm run dogfood
That command checks task-folder hygiene, current loop status, public docs hygiene, dependency audit results, harness upgrade state, review gates, artifact inventory, maintainer reviewability, agent review context, AgentFlight health, and ProjScan health. It does not publish packages, create tags, post comments, read tokens, read .env contents, or run verification commands.
Use JSON output when an agent or CI job needs a structured dogfood summary:
npm run dogfood:json
npm run dogfood:strict:json
The JSON summary reports the mode, overall status, step results, exit codes, durations, and safety notes. It redacts the current workspace root as [git-root] before printing structured output.
Run the public-doc check by itself when you edit README, examples, or release-channel docs:
npm run check:public-docs
Use the stricter gate before a release or final handoff:
npm run dogfood:strict
Use the maintenance gate when typecheck, release-proof or npm-status command health, public docs, SchemaStore, policy packs, GitHub metadata, AgentFlight, or ProjScan behavior changes:
npm run maintenance:check
maintenance:check covers unit tests, typecheck, public docs, links, non-strict npm release-proof smoke coverage, read-only npm-status safety tests, SchemaStore output and consistency tests, policy-pack inventory and safety tests, GitHub metadata safety and ship-score neutrality tests, AgentFlight, ProjScan, and the non-strict dogfood self-check. Use npm run dogfood:strict after fresh handoff or ship evidence exists, when review-gate warnings should block the handoff. maintainer-check warnings remain reviewer guidance unless the command exits non-zero. Strict public release proof remains part of approved release gates.
AgentLoopKit MCP questions
How do I add AgentLoopKit MCP to Claude Code?
Run claude mcp add agentloopkit -- npx -y agentloopkit in your terminal. Add --scope user to make it available in every project.
How do I add AgentLoopKit MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What does AgentLoopKit do for software agents?
It provides a local acceptance layer including task contracts, safety rules, verification evidence, and review-readiness scores for engineering agents.
How do I initialize AgentLoopKit in my repository?
You can initialize it by running npx agentloopkit init inside your repository.
Can I use AgentLoopKit without committing the generated files?
Yes, you can use the --local-only flag during initialization to write the harness to a local-only metadata directory without editing your project files.
Does AgentLoopKit execute coding agents or post to GitHub?
No, the tool manages the workflow and documentation but does not execute agents or interact with external services like GitHub directly.