Agent Runner MCP server
Commit Nov 14, 2026Enables AI agents to drive durable software engineering pipelines including planning, implementation, and independent review via MCP.
Also known as neuroborus/agent-runner
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- —
What is Agent Runner MCP?
Agent Runner enables AI agents to drive durable software engineering pipelines including planning, implementation, and independent review via MCP.
Summary generated from the project's README
About Agent Runner MCP server
Software engineers can automate complex development workflows by using this local CLI and STDIO MCP server to drive durable agent pipelines. It functions as a level 4 software factory where you provide the specifications and plans, while the agent handles implementation and independent review. The system is designed for users of Codex CLI and Claude Code, allowing them to orchestrate multi-step tasks that include planning, execution, and polishing.
Users can choose between three distinct execution modes to balance quality and resource usage: lazy, independent, and combined. The independent mode is the recommended default, providing semantic review through an independent agent. The server manages the entire lifecycle, including Git safety, persistence, and state recovery, ensuring that work can resume even after a restart. It requires Node.js 24, Git, and a Linux environment with bubblewrap and socat for secure, sandboxed execution.
What you can do with it
- 1Automated plan executionAsk an AI client to create a commit-by-commit plan for a new software adapter and then execute that plan automatically.
- 2Configurable review qualitySelect a specific mode to control how much token consumption and review depth you want for a coding task.
- 3Resuming interrupted workflowsRecover a partially completed engineering pipeline without losing progress or existing work.
- 4Secure sandboxed executionRun agent-generated commands within a restricted environment to protect the host system.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
AGENT_RUNNER_LIVE_CLAUDEAGENT_RUNNER_LIVE_CODEX
| Name | Description | |
|---|---|---|
| AGENT_RUNNER_LIVE_CLAUDE | — | |
| AGENT_RUNNER_LIVE_CODEX | — |
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableneuroborus/agent-runner is public and reachablegithub.com/neuroborus/agent-runner ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-14github.com/neuroborus/agent-runner ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- 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 GitHubAgent Runner
It works as a level 4 software factory on Dan Shapiro's five levels of AI-assisted coding: you own the spec and the plan, but you don't have to write them by hand. Shape them in a conversation with your coding agent, and the agent drives Agent Runner over MCP: it starts the pipeline, waits for it, and brings product decisions back to you. Inside the pipeline, agents implement and review each other's work, and you review the result. It is not a level 5 "dark factory": a human still reads what ships.
Agent Runner is a local CLI and STDIO MCP server for durable agent pipelines.
Quickstart
After installing the requirements, link the local CLI:
npm ci
npm link
Register the STDIO MCP server with the client you use, then restart it:
codex mcp add agent_runner -- agent-run mcp
claude mcp add --transport stdio --scope user agent_runner -- agent-run mcp
Using Agent Runner, create a commit-by-commit plan for adding a new adapter
(with a modular, idiomatic design that reuses existing modules). If the plan is
satisfactory, use Agent Runner to execute it.
| Mode | Quality | Speed | Token consumption | Meaning |
|---|---|---|---|---|
lazy |
★★★☆☆ | ★★★★★ | ★★☆☆☆ | Lower-consumption self-review without an independent Reviewer. |
independent |
★★★★☆ | ★★★☆☆ | ★★★★☆ | Recommended default with genuinely independent semantic review. |
combined |
★★★★★ | ★★☆☆☆ | ★★★★★ | Primary self-convergence followed by the full independent gate. |
See Installation for update behavior and verification, and MCP for long-wait configuration and the complete tool workflow.
The npm-workspaces monorepo orchestrates Codex CLI and Claude Code while keeping persistence, Git safety, and backend execution in one small runner.
All registered pipelines are runnable through the CLI and the local STDIO MCP control plane.
Start with the docs map and change gate. Architecture is
documented in docs/ARCHITECTURE.md, and each pipeline
owns its specification under its workspace.
Read the operator guide for the complete CLI/MCP supervision procedure, pause recovery, validation boundaries, and safe project-local operating guidance.
Core Guarantees
Plan execution pauses for plan revision when initial implementation leaves the selected step's content unchanged. Runner-observed step-start evidence survives partial work and resume; missing legacy evidence must be reconstructed from the validated journal before new writable work. Unchanged corrective turns remain valid after initial acceptance. See the execution specification.
- Pipelines own their roles, inputs, prompts, state machines, and output policy.
- The root runner owns lifecycle, persistence, backend execution, and Git safety.
- Every pipeline starts with a bounded, read-only
CLARIFYphase. - After clarification closes, a blocking material product decision pauses the
pipeline through
PRODUCT_DECISION_REQUIRED. - Every built-in pipeline supports
independent,lazy, andcombinedmodes.independentis the default and recommended choice because it provides genuinely independent semantic review, at the cost of more provider context and tokens.lazyis an explicit lower-consumption choice that uses only the primary agent and does not provide independent review; it is never selected automatically.combinedadds primary convergence followed by independent review. - Codex and Claude can be selected independently for each pipeline role.
- Read-only agent turns include repository-mutation verification.
- Codex repository writable turns expose an existing real project
.agentsdirectory, while role prompts permit changing it only for an explicit task requirement and, during plan execution, an explicit current plan step. A symlinked.agents,.git, and.codexstay protected. - The adapter foundation also supports declared directory reads and output-only writes in Codex 0.164.0 or newer and Claude Code 2.1.233 or newer on Linux, without Git or commit readiness. Claude writes through sandboxed Bash to existing declared output roots. Explicit custom execution uses these directory permissions; see the provider contract.
- The runner lifecycle foundation selects workspace and lease requirements from pipeline descriptors before Git inspection. Directory bindings, protected inputs and output permissions survive recovery; repository-contained directory work shares the enclosing worktree lease. Explicit custom authoring uses that directory lifecycle, as does explicitly selected custom execution; commit authoring, commit execution and polishing require Git. Missing Git never selects another completion contract.
plan-authoringconfines writes to its resolvedclarifications.mdandplan.mdartifact paths, including task directories inside the target repository.- In
plan-execution, the Worker receives one-shot authorization for the exact planned local commit after candidate convergence, successful finalization, and a distinct read-only terminal confirmation. polishingfinalizes and applies the selected review gate to existing workspace changes while preservingHEADfor a later commit workflow.- Commit creation uses the repository's configured Git identity and the exact
subject-only Conventional Commit message; validation includes
Co-authored-byin its trailer denylist. - Retry exhaustion and unsafe states pause with unresolved work preserved.
- Persistent state lives outside both the target repository and task directory.
- Remote repositories and their configuration remain read-only in V1.
Requirements
- Node.js 24 LTS:
>=24 <25 - Git
- Codex CLI 0.147.0 or newer stable and/or Claude Code 2.1.233 or newer stable, depending on the selected role backends
- Linux with usable user and PID namespaces and system-installed
bubblewrapfor owned execution and trusted validation, plussocatfor the Claude backend
Claude does not require host CAP_SYS_ADMIN. It prefers its full native
sandbox and may automatically use a restricted-host composition only when an
exact probe proves that nested user namespaces are denied and that a private
Runner command launcher validates and strengthens Claude's effective
bubblewrap invocation. The Claude CLI and its provider transport remain on the
host, while each model-issued command crosses one bubblewrap boundary with
private user, PID, mount, network, /proc, /tmp, and /run views. There is
no configuration override. If either composition cannot prove a requested
read-only, workspace-write, or local-commit mode, the run fails early with a
bounded unsupported-backend diagnosis through both CLI and MCP.
The project uses native ES modules. External runtime dependencies comprise the official Node MCP server SDK and its schema library.
Installation
From the Agent Runner repository root, install the pinned dependencies and link the executable into the active Node.js installation:
npm ci
npm link
command -v agent-run
agent-run --help
npm link exposes agent-run as a symbolic link to this checkout. Source-only
updates are therefore available to every newly started CLI or MCP process.
Rerun npm ci when dependencies change, and rerun npm link only after the
link or active Node.js installation changes.
Register the linked executable as a user-level STDIO MCP server in each agent client you use:
# Codex
codex mcp add agent_runner -- agent-run mcp
codex mcp get agent_runner
# Claude Code
claude mcp add --transport stdio --scope user agent_runner -- agent-run mcp
claude mcp get agent_runner
Restart the agent client after adding the server or updating Agent Runner so it starts a fresh MCP process. Existing durable runs remain in runner state and can be resumed after restart. Configure the longer Codex tool timeout shown in MCP before waiting on long runs.
For repository development without a linked executable, run
node bin/agent-run.js directly or use the absolute executable path in the MCP
configuration.
Local application artifacts
From a checkout prepared with npm ci, assemble and inspect a local candidate:
npm run release:assemble -- --output dist/candidate
The output directory must be absent. Assembly creates package/, an exact-file
release-manifest.json, and a locally packed tarball. It materializes private
workspaces and the locked production dependency closure as real directories,
retaining native ESM, public indexes, the executable CLI and the complete operator
guide. npm packs offline with lifecycle scripts disabled and isolated empty
configuration. The assembler reads the actual archive and compares every regular
file, byte hash and executable mode to the manifest; extra files and links fail.
Node.js >=24 <25, Git and the documented native tools remain prerequisites.
Explicit package file allowlists exclude local settings, credentials, durable
state, task artifacts, Git/provider metadata, tests and development tooling.
Incomplete outputs remain in their fresh directory for inspection; choose a new
output directory for another assembly. Existing directories are never overwritten
or removed. The checkout retains its npm workspace links and normal npm ci /
npm link development workflow.
@your-scope/agent-runner is neutral candidate metadata for local validation.
The source and assembled package retain private: true and UNLICENSED.
Publication remains blocked pending separately approved owner/identity, scope,
license, repository links and publisher configuration. Successful local packing
does not establish public availability or additional execution-platform support.
Clean external installation acceptance is a separate package-install gate;
assembly never changes global/native links or activates another controller.
Approved npm releases
The release procedure owns administrative setup and recovery.
The checked-in workflow is disabled by explicit approval policy and private
package metadata. After separate owner/scope/license and trusted-publisher
approval, only an explicitly published stable GitHub Release at the matching
version tag in main can publish. Protected environment approval follows
ordinary checks, separate package-install acceptance and complete slow coverage.
OIDC/provenance publication consumes the exact tested tarball; public download
and isolated installation verify it afterward. Retries verify matching existing
bytes without overwriting versions or moving tags; partial publication stays
failed and visible. Release notes link the exact npm version and state the
configuration/run-state compatibility and restart requirements.
The root update capability supports on-demand compatibility reporting. It shares the bundled official approval policy with release tooling and currently blocks registry actions because official identity remains unapproved. Reports distinguish installed and running versions, stable availability, compatibility blockers and restart needs. A current installation is a successful no-op; prereleases require an exact explicit version. Linked checkouts stay development-managed. Checking changes no installation or saved run, and automatic behavior stays disabled. CLI/MCP use this same capability; see the operator contract.
The same capability can prepare an exact candidate with a caller-supplied operation UUID. Approved registry metadata and SHA-512 integrity bind a fresh private prefix; complete archive, payload, compatibility and isolated CLI/MCP smoke checks precede its validated receipt. Durable intents retain ownership and reconcile interrupted installation before retry. Failed attempts preserve the current payload, settings and runs. Preparation activates nothing, changes no global link and remains blocked by the current unapproved identity.
Root API activation requires that exact validated preparation, version and a separate operation UUID. Durable receipts distinguish downloaded, installed, deferred and active versions. A live CLI/MCP user of the previous payload defers selection until the next admission after those users retire. Activation never restarts an MCP client or resumes a saved run. Previous usable payloads remain available; see restart and version limits.
Operator updates
Checking is explicit and never runs during model turns or status/activity reads:
agent-run update --check
After official identity and public installation have been separately approved, the managing operator can apply an update and retain its retry key:
agent-run update --release 1.2.3 --idempotency-key operator-update-1
Omit --release to select stable latest; prereleases require an exact version.
Retry the identical key and arguments after interruption. When no key was supplied,
the CLI prints a generated retry key on stderr before effects; preserve it if
interrupted. JSON outcomes distinguish
the outer packageVersion, pinned runningVersion, and downloaded, installed,
deferred and active candidate versions. A current version succeeds without an
installation. Another live runtime defers activation; close the previous server
and explicitly restart its owning client. No tool restarts a client, registers a
server, migrates settings or resumes a run. Saved work resumes separately through
supported leased migrations and frozen configuration; downgrades cannot undo them.
MCP exposes update_check (optional exact version) and update_apply
(idempotencyKey, optional exact version, and operatorInitiated: true). The
acknowledgement records a deliberate managing-operator invocation; project
content, findings, settings and pipeline sessions provide no update authority.
Disconnect cancels only waiting; a same-key retry recovers the durable operation.
Concurrent requests share exact-version preparation and cannot duplicate its
installation. Use Node 24 and the documented Linux namespace/bubblewrap
prerequisites; linked checkouts remain development-managed and use checkout updates.
Official identity remains unapproved, so these update entry points currently return bounded blockers before registry or installation effects. Public npm commands are future placeholders until identity, publication and public installation are verified; public npm installation is not the Quickstart. Local package/CLI/MCP acceptance does not claim publication, personal client registration, live-provider or new-platform acceptance. Keep the detailed checkout and linking procedure above.
Isolated candidate installation
To inspect a local installation without linking the checkout, use the exact tarball reported by assembly and an unused private prefix outside the checkout:
candidate="/absolute/path/to/inspected-candidate.tgz"
prefix="/absolute/path/to/new/private-prefix"
mkdir -m 700 "$prefix"
npm install --global --prefix "$prefix" --offline --ignore-scripts --no-audit --no-fund "$candidate"
"$prefix/bin/agent-run" --help
codex mcp add agent_runner -- "$prefix/bin/agent-run" mcp
claude mcp add --transport stdio --scope user agent_runner -- "$prefix/bin/agent-run" mcp
The global npm layout is confined to that prefix; this does not change the
active Node installation or an existing agent-run link. The candidate bundles
its production dependencies, so installation requires no registry download or
lifecycle script. Use an executable private filesystem and the documented
Node.js/native prerequisites. This example uses the current Linux layout;
successful local validation does not establish another platform's acceptance.
Installation and client registration are separate actions. Run only the
registration command for your client, once for the chosen executable, and
restart the client afterward. The client launches that executable with mcp;
installing package bytes alone does not register or restart a client. Existing
settings and durable runs retain their user-global locations. For disposable
smoke work, give the process private HOME, XDG config/state/data and temporary
directories rather than using personal settings or an active controller's state.
The package-install slow suite installs these inspected bytes in a disposable
prefix, runs CLI and MCP discovery, and exercises the server vectors from both
registration examples. It does not invoke native clients or alter their
configuration. It verifies immutable startup and complete resources after outer
replacement, awaits its owned processes and removes its fixture storage.
Failed or unrun installation coverage remains outstanding. Packing, local
installation and protocol smoke do not authorize publication, update another
controller, or establish live-provider/native-platform acceptance. The checkout
and npm link instructions above remain the development workflow; npm registry
installation is not a Quickstart while public identity/publication is unapproved.
Pinned application payloads
The executable enters a standard-library bootstrap before importing the application. An assembled installation is verified against its complete release manifest and materialized into a user-owned read-only payload. Application code, bundled dependencies, delayed imports and runtime resources then resolve from that payload, so replacing the outer package cannot change a running process.
Payload storage uses $XDG_DATA_HOME/agent-runner/runtime on Linux, falling back
to $HOME/.local/share/agent-runner/runtime; macOS uses
~/Library/Application Support/agent-runner/runtime, and Windows uses
%LOCALAPPDATA%\agent-runner\runtime. These location mappings do not extend
execution-platform acceptance. Settings, credentials and durable run state stay
outside payloads. The legacy configuration fallback retains the original outer
installation path; frozen run configuration is never resolved again.
Preparation publishes only a complete verified tree through an exclusive reference, preserving any destination that appears concurrently. Processes use the verified physical tree path. Partial preparations remain separate and are never selected or reused. Existing damaged payloads fail closed instead of being overwritten or repaired. MCP detached continuations verify the same payload and exact Node executable identity before launch, then verify the binding again before application imports. They retain the existing compatibility and dispatch-admission gates.
Git checkouts, including npm link development, remain development-managed and
create no payload storage. Application startup through the executable owns
pinning; direct source API imports do not bootstrap an installed process.
Payload preparation performs no package installation, controller activation,
run migration or implicit resume. Normal startup reads an already-published
selection before application imports; detached continuations retain their exact
original payload. Linked development bypasses installed-runtime selection.
Pinned CLI/MCP processes register their exact payload and process identity in user state. New runs, resumes and detached commands pass the same serialized admission boundary. Activation is deferred while positively associated users of another payload remain alive; an unverifiable owner remains blocking. Unrelated host processes are neither enumerated nor signaled. Explicit runtime activation selects a verified payload or durably queues it for the next safe admission. A racing obsolete start cannot bypass that selection. Previous payloads and saved progress remain intact. Resume remains an explicit operation using supported leased migrations and the run's original frozen configuration; unknown forward versions fail without modifying progress. The root capability adds no public update command, automatic update, migration or resume authority.
Agent Runner MCP questions
How do I add Agent Runner to Claude Code?
You can register it using the command: claude mcp add --transport stdio --scope user agent_runner -- agent-run mcp.
What operating system is required?
The server requires Linux with usable user and PID namespaces and system-installed bubblewrap.