BootstrapAgent: Reusable Repo Bootstrapping

• BootstrapAgent is a multi-agent framework that formalizes repository setup as a reusable, deterministic .bootstrap contract to solve the cold repo problem.
• It encapsulates installation commands, diagnostic checks, verification steps, and repair heuristics into a contract that can be replayed and audited.
• Empirical results show a 92.9% clean-replay success rate with significant savings in token usage and build time over competing methods like HerAgent.

Searching arXiv for the specified BootstrapAgent paper and closely related work to ground the article. BootstrapAgent is a multi-agent framework for repository bootstrapping that treats startup configuration not as an ephemeral interaction artifact but as reusable startup knowledge distilled into a persistent, verifiable, agent-consumable .bootstrap contract (Fu et al., 15 May 2026). It addresses the “cold repo” problem encountered when code agents must work with unfamiliar repositories: they must rediscover dependency installation, environment configuration, and minimal verification through costly trial-and-error exploration. BootstrapAgent formalizes the resulting setup commands, diagnostic checks, verification commands, and repair heuristics so that they can be deterministically replayed, audited, and reused by future agents or humans. On 212 repositories across three public suites, it reports a 92.9% clean-replay success rate, outperforming HerAgent by 8.5 percentage points overall while reducing downstream agent token usage by 25.9% and build time by 22.3% (Fu et al., 15 May 2026).

1. Problem formulation and motivation

Modern code-generation agents frequently encounter the “cold repo” problem: given an unfamiliar Git repository $R$, they must infer how to install dependencies, configure the environment, and run even a minimal test. The bootstrap loop described for this setting consists of reading README files, CI workflows, and lockfiles; guessing setup commands such as pip install -r requirements.txt; executing them; observing failures; repairing the environment; and retrying (Fu et al., 15 May 2026).

The key claim of BootstrapAgent is that the knowledge produced by this exploration is usually discarded at the end of a single conversation, even though it includes resolved dependency pins, working-directory fixes, and repair strategies that are valuable for future runs. BootstrapAgent reframes repository bootstrapping as a reusable startup-knowledge problem. Instead of preserving only an interaction trace, it synthesizes a contract that captures setup, diagnostics, verification, and accumulated repair knowledge in a form that is deterministic-replayable and auditable (Fu et al., 15 May 2026).

This framing has two consequences. First, bootstrapping becomes an explicit systems problem rather than an incidental prelude to downstream software engineering. Second, reproducibility becomes a first-class acceptance criterion: a setup is not merely “working once,” but working under deterministic re-execution in a fresh Docker environment. This suggests that BootstrapAgent is as much a verification framework as it is a setup assistant.

2. The .bootstrap contract

BootstrapAgent formalizes repository setup as a contract

$C \;=\; (I,\,D,\,M,\,S,\,H),$

where $I$ is an ordered list of environment installation or setup shell commands, $D$ is a list of read-only diagnostic checks, $M$ is a single minimal verification command, $S$ is an optional “strong” verification command captured from reproducible CI evidence, and $H$ is the compressed repair-knowledge history represented as a small playbook of past delta patches that fixed failures (Fu et al., 15 May 2026).

The roles of these components are differentiated rather than redundant. The installation list $I$ specifies the actual environment-construction procedure. The diagnostic list $D$ encodes non-mutating checks such as import probes. The minimal verification command $M$ provides the strict acceptance target for the contract. The optional strong verification command $C \;=\; (I,\,D,\,M,\,S,\,H),$0 is not required to pass under the strict success criterion, but it functions as a guardrail against weakening $C \;=\; (I,\,D,\,M,\,S,\,H),$1 during repair. The repair history $C \;=\; (I,\,D,\,M,\,S,\,H),$2 compresses prior successful deltas into reusable heuristics rather than preserving the full exploration trace (Fu et al., 15 May 2026).

Each command carries provenance metadata linking it back to lines or snippets in the extracted repository evidence $C \;=\; (I,\,D,\,M,\,S,\,H),$3. This provenance requirement matters because BootstrapAgent is designed not only to generate executable setup scripts, but also to justify them against repository artifacts such as README files, lockfiles, package metadata, and CI workflows.

Execution semantics are defined inside a Docker base image $C \;=\; (I,\,D,\,M,\,S,\,H),$4 by running setup.sh, then doctor.sh, then verify.sh. A contract is valid iff all three stages pass: $C \;=\; (I,\,D,\,M,\,S,\,H),$5 The explicit exclusion of $C \;=\; (I,\,D,\,M,\,S,\,H),$6 from the strict validity predicate is important: $C \;=\; (I,\,D,\,M,\,S,\,H),$7 acts as a guardrail rather than the formal acceptance target (Fu et al., 15 May 2026).

3. Multi-agent decomposition and control flow

BootstrapAgent comprises five collaborating sub-agents: Discoverer, Planner, Generator, Verifier, and Repairer (Fu et al., 15 May 2026). Discoverer extracts $C \;=\; (I,\,D,\,M,\,S,\,H),$8 by scanning repository artifacts such as README files, lockfiles, package metadata, and CI workflows. Planner converts $C \;=\; (I,\,D,\,M,\,S,\,H),$9 into an abstract BootstrapPlan $I$0 that outlines phases and verification goals. Generator materializes an initial .bootstrap contract $I$1. Verifier runs the contract deterministically in Docker and produces an execution trace $I$2. Repairer examines $I$3 relative to $I$4 and proposes a minimal delta $I$5 to fix failures.

The control loop is iterative. BootstrapAgent begins by discovering repository evidence, planning, and generating an initial contract. It then repeatedly verifies the current contract, checks whether $I$6, $I$7, and $I$8 all passed, performs a clean replay when warm execution appears successful, and otherwise computes and applies a repair delta. The contract update rule is written as

$I$9

where the trace $D$0 captures exit codes and logs (Fu et al., 15 May 2026).

Two properties of this architecture are central. First, generation and repair are separated: the system does not regenerate the entire contract after every failure. Second, verification is deterministic and Docker-based, so the trace used for repair is grounded in a controlled execution environment rather than in a free-form conversational interpretation of failure logs.

A related line of work on agentic orchestration, AOrchestra, models any agent as a tuple $D$1 of Instruction, Context, Tools, and Model, and lets an orchestrator instantiate specialized sub-agents on demand (Ruan et al., 3 Feb 2026). A plausible implication is that BootstrapAgent’s five-agent pipeline can be understood as a fixed orchestration policy over specialized roles, whereas AOrchestra emphasizes dynamic sub-agent creation and model/tool routing. The two systems therefore occupy related but distinct points in the design space of multi-agent software automation.

4. Verification, warm repair, and anti-degradation safeguards

BootstrapAgent’s Verifier has two modes: warm and cold. Warm verification, described as “hot-reload,” reuses the same container state to test small command patches quickly. Cold verification, or clean replay, reruns the accepted contract in a fresh container to ensure that no residual state or cache hid a problem (Fu et al., 15 May 2026).

Warm repair is introduced to accelerate iterative debugging without sacrificing cold-start reproducibility. Within each iteration, the system tests $D$2 in the existing Docker container, and the reported effect is that iteration is often 2–3× faster than performing a full cold restart on every repair step (Fu et al., 15 May 2026). Clean replay then acts as the reproducibility gate: once warm repair reports success, the contract is frozen and rerun in a fresh container, and only if the cold run still passes is the contract accepted.

Repair is explicitly delta-based. Rather than regenerating the entire .bootstrap directory from scratch, Repairer proposes a minimal structured patch $D$3, described as an insert, replace, or move affecting one or two commands and guided by the failure trace. The stated rationale is twofold: it reduces token cost because only the failing portion is re-generated by the LLM, and it limits drift and hallucination because previously validated commands remain untouched (Fu et al., 15 May 2026).

BootstrapAgent also incorporates a sanity check intended to prevent reward hacking. If a repair delta modifies $D$4 or weakens any command justified by repository evidence $D$5 or by the plan $D$6, the delta is rejected. The paper gives the example of replacing a real smoke test with python --version; such a weakening is disallowed. Deltas that violate evidence-supported targets or the strongest-verify $D$7 guardrails are likewise rejected (Fu et al., 15 May 2026). A common misunderstanding would be to treat any passing minimal command as success. BootstrapAgent’s design rejects that interpretation by combining provenance constraints, optional strong verification, and clean replay.

5. Empirical evaluation

The evaluation covers 212 repositories across three public benchmarks: Repo2Run-Bench with 122 Python repositories, ExecutionAgent-Bench with 50 polyglot repositories spanning JavaScript, C/C++, Python, and Java, and Installamatic-Bench with 40 Python repositories. The baseline is HerAgent, described as the state-of-the-art rule+agent bootstrap tool. Reported metrics include clean-replay success rate, generation token usage, wall-time per repository, and downstream cold-versus-warm bootstrap savings for the Claude Code agent (Fu et al., 15 May 2026).

End-to-end effectiveness

Benchmark	HerAgent	BootstrapAgent
Repo2Run-Bench	104/122 (85.2%)	117/122 (95.9%)
ExecutionAgent-Bench	41/50 (82.0%)	42/50 (84.0%)
Installamatic-Bench	34/40 (85.0%)	38/40 (95.0%)
Overall	179/212 (84.4%)	197/212 (92.9%)

The overall improvement is +8.5 percentage points, with the largest gains appearing on Repo2Run-Bench (+10.7 points) and Installamatic-Bench (+10.0 points), while ExecutionAgent-Bench shows a smaller +2.0-point gain (Fu et al., 15 May 2026). This distribution suggests that BootstrapAgent’s contract-and-repair design is especially effective in settings where reproducible environment construction dominates difficulty.

Generation cost is reported as a median of approximately 43.8K tokens per repository and a median wall-clock time of approximately 24.6 minutes, with the 90th percentile at approximately 169K tokens and 79 minutes (Fu et al., 15 May 2026). Those figures indicate that the framework incurs nontrivial upfront synthesis cost, but the authors position this cost against repeated downstream reuse.

Downstream transfer

Metric	Cold	Warm
Time	346.3 s	249.5 s
Tokens	46.3 K	36.9 K

Using .bootstrap as a warm start rather than bootstrapping from scratch yields a time ratio of $D$8 and a token ratio of $D$9, corresponding to savings of 22.3% in time and 25.9% in tokens for paired runs with Claude Code (Fu et al., 15 May 2026). ExecutionAgent-Bench shows the largest downstream gain, with time ratio 0.39 and token ratio 0.19. These results are consistent with BootstrapAgent’s central claim that setup knowledge, once distilled into a contract, can amortize bootstrap cost across future agents.

6. Scope, limitations, and related directions

BootstrapAgent targets local boot readiness rather than full CI success or semantic correctness. The paper explicitly notes that many CI pipelines require secrets or services, so successful local bootstrap should not be conflated with end-to-end deployment validity (Fu et al., 15 May 2026). It also notes that underspecified repositories, such as those missing a Python or JDK version, may induce brittle guesses. Repeated repair may overfit to warm state but fail clean replay, which is precisely why cold verification is retained as the final gate.

A further limitation is temporal maintenance. Once generated, .bootstrap must be maintained alongside repository evolution (Fu et al., 15 May 2026). This implies that the framework is not a one-time extraction mechanism; its value depends on whether the contract remains synchronized with changing dependencies, CI logic, and verification targets.

The future-work directions listed for BootstrapAgent include stronger dependency-solver integration and version inference from Git history, automated recovery of external artifacts such as Docker images and large-model downloads, support for GPU and cloud-service containers as well as service-oriented integration tests, and tight integration with repository metadata for automatic .bootstrap updates (Fu et al., 15 May 2026). These extensions all preserve the central architecture: explicit evidence extraction, structured planning, deterministic verification, and repair constrained by provenance and replayability.

In a broader orchestration context, AOrchestra proposes a framework-agnostic abstraction in which any agent is represented as $M$0, and the orchestrator dynamically chooses task-relevant context, tools, and models to balance performance and cost (Ruan et al., 3 Feb 2026). This suggests a possible convergence between persistent repository startup knowledge and dynamic agent instantiation: BootstrapAgent contributes a reusable contract for local repository readiness, while AOrchestra contributes a generalized theory of sub-agent creation and cost-aware delegation. The former is centered on verifiable repository setup; the latter is centered on adaptable orchestration across long-horizon tasks.