Capsule
Capsule is an agent-neutral Rust library and CLI for isolated, recoverable code-change attempts — each sealed into a portable, verifiable receipt.
It does not run an agent. It gives any agent or automation system a safe place to work, and it gives everyone downstream — reviewers, CI jobs, merge gates — a durable result whose integrity can be re-checked anywhere with capsule verify, without access to the original workspace, session, or state directory.
pinned Git commit
│
├── capsule A ── ordinary worktree ── sealed patch + provenance
├── capsule B ── ordinary worktree ── sealed patch + provenance
└── primary worktree remains unchanged until explicit integration
A capsule is more than a Git worktree. It records the complete boundary of an attempt:
- collision-resistant identity;
- exact repository and base commit;
- isolated ordinary filesystem path;
- optional links to tasks, runs, agents, or external systems;
- checkpoints created during the attempt, including crash-recoverable checkpoint journals;
- caller-recorded verification evidence;
- complete binary-capable patch, changed-path inventory, and sealed provenance;
- discoverable, streamable artifacts with file URIs and SHA-256 content addresses;
- exported receipts that verify offline, with no capsule state required;
- bounded structured lifecycle audit events and aggregate metrics;
- configurable repository, count, age, size, patch, path, and ignored-content policy;
- explicit state inspection and backup;
- immutable result digest and drift detection;
- explicit, journaled integration;
- guarded cleanup and crash recovery.
No daemon, VFS, container, shell interpreter, object store, task tracker, model SDK, or agent framework is required.
Who can use it
Any process that can consume a path or JSON can use Capsule: interactive coding agents, headless agents, IDE agents, CI jobs, eval harnesses, task trackers, multi-agent coordinators, and custom scripts.
Capsule does not contain adapters for particular agents. This is intentional. The stable integration surface is:
- call the CLI with
--jsonor embed the Rust crate; - give the returned
workspace_pathto the agent as its working directory; - let the agent use its existing file, search, shell, and Git tools;
- record optional evidence;
- close the capsule and inspect, verify, or integrate its result.
The stable handoff surface is the exported receipt: bundle.json, result.json, and result.patch, content-addressed and verifiable by capsule verify on any machine with Git. A harness that emits receipts and a reviewer that checks them never need to share a filesystem, a state directory, or a tool version.
For a complete runnable walkthrough — two competing attempts, sealed receipts, tamper detection, explicit integration — run examples/parallel-attempts.sh.
Install
Prerequisites:
- Git on
PATH; - Rust 1.85 or newer when building from source.
That installs the capsule binary. The crate is registered as change-capsule because capsule was already taken on crates.io; the command you run is capsule.
For library-only use without the Clap CLI dependency:
[]
= { = "0.1", = false }
Quick start
Create two independent attempts from the same pinned HEAD:
Each response includes an ID, path, branch, and resolved base commit. Start any agent or command with workspace_path as its current directory.
Inspect an active attempt:
Optionally create a recoverable checkpoint. Checkpoint commits are prepared through a private index, journaled, then atomically advanced onto the capsule branch; recover finishes an interrupted transition:
Record verification performed by the caller:
Seal and discover the result. --require-successful-evidence rejects missing or failed evidence:
Verify the receipt anywhere — on the same machine, in CI, or after copying ./handoff to a reviewer. Verification needs no capsule state; --repo additionally proves the sealed patch applies to the pinned base and reproduces exactly the sealed bytes and changed paths:
artifacts reports media types, byte lengths, file:// URIs, and sha256: content addresses. Artifact readers, publishers, and exports consume one bounded, validated byte snapshot, so later filesystem mutation cannot change the bytes described by that operation. export reserves a new destination directory without clobbering, moves in result.json and result.patch, then publishes bundle.json last as the completion marker.
Integrate only the selected result into a clean worktree that is still at the pinned base:
Cleanup removes only the capsule-owned worktree and branch. Its manifest, patch, result, and evidence remain:
CLI
capsule create create an isolated attempt from a resolved base commit
capsule list list durable capsule records
capsule show show the full manifest
capsule path print the ordinary filesystem workspace path
capsule status inspect health, changed paths, commits, and seal state
capsule diff emit the complete current or sealed patch
capsule result show the sealed handoff manifest
capsule artifacts discover sealed artifacts, URIs, sizes, and content addresses
capsule export create a self-describing result artifact directory
capsule verify verify an exported receipt offline, optionally against a repository
capsule audit show one capsule's events or the administrative event stream
capsule metrics show aggregate lifecycle and storage counters
capsule policy show, replace, or evaluate resource/repository policy
capsule state inspect or back up durable state
capsule checkpoint commit current work with an explicit identity
capsule evidence record externally-run verification evidence
capsule close seal patch, inventory, evidence, and digest
capsule integrate explicitly apply one sealed result to its pinned base
capsule drop safely remove an owned worktree and branch
capsule recover reconcile interrupted journal states
Merge gate
A receipt is only useful if something checks it. This repository ships a GitHub Action that verifies a receipt in CI and, with verify-head, refuses the merge unless the tree being merged is exactly the pinned base plus the sealed patch:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # the pinned base must be present
- uses: SiliconState/change-capsule@v0.1.2
with:
bundle: ./receipt # produced by `capsule export`
repo: .
require-successful-evidence: "true"
verify-head: "true"
The gate passes only when every one of these holds:
- the bundle's artifacts match their descriptor digests and byte counts;
- the sealed result is internally consistent and its schema is supported;
- the pinned base exists in the checkout and the sealed patch applies to it, reproducing exactly the sealed bytes and changed paths;
- evidence exists and every recorded exit code is zero;
- the checked-out tree equals base plus the sealed patch.
Together those mean the diff being merged is the diff that was sealed and verified — established without trusting the machine that produced it. Outputs (verified, capsule-id, base-commit, patch-sha256, changed-paths) are available to later steps, and the run publishes a job summary table.
The same checks run locally with no Action involved:
Mandatory committed-receipt protocol
A receipt cannot describe a commit that contains the receipt itself: adding bundle.json, result.json, and result.patch changes the tree. For repositories that commit receipts, use this exact two-commit protocol:
- Create the capsule from the branch base and do all implementation work in its workspace.
- Run verification in that workspace and record the real command and exit code with
capsule evidence. - Close with
--require-successful-evidence, export the receipt, and integrate the sealed result. This creates the implementation commit. - Make one second commit that adds only
receipts/required/bundle.json,result.json, andresult.patch. Do not amend, squash, or add unrelated files. - Push both commits. If the branch is rebased or implementation changes, the old receipt is stale: create a new capsule from the new base and repeat.
The required receipt-gate job in this repository enforces the protocol. scripts/prepare-committed-receipt.sh rejects a dirty checkout, merge commit, malformed receipt path, missing artifact, or any non-envelope change in the tip commit. It checks out the tip's sole parent and identifies that implementation commit's base. SiliconState/change-capsule@v0.1.2 then verifies the committed bundle, successful evidence, exact pinned base, and implementation tree byte-for-byte; pull requests additionally require that pinned base to equal GitHub's current base SHA. Configure this job as a required branch check and use rebase or fast-forward merges that preserve the two commits; a squash merge deliberately destroys this binding.
capsule evidence records a command claim and exit code supplied by the caller; it does not execute the command or provide signed attestation. The gate proves receipt integrity and tree binding, while CI should still rerun security-critical tests independently.
CLI details
--json is global. Errors are emitted as one JSON object on stderr in JSON mode. capsule diff --json returns metadata rather than embedding arbitrary patch bytes; pass --output <file> for patch data. Policy failures use error kind policy; unknown artifact requests use artifact_not_found.
State defaults to the platform state directory and can be overridden with CAPSULE_HOME or --home.
Policy and operations
An absent policy.json means permissive defaults subject to hard safety bounds. Replace policy atomically from a versioned JSON document and evaluate existing state separately:
Policy supports allowed repository roots and optional limits for total/live capsule count, capsule age, state/workspace bytes, result patch bytes, changed paths, ignored paths, and ignored bytes. Result limits apply to the complete base-to-current result, including when a checkpoint contains only a smaller incremental change. Mutating operations fail before their principal side effect when the applicable limit is exceeded. Usage that no configured limit references is not measured, so the permissive default policy adds no directory walks or content inspection to lifecycle operations. policy check is observational: it evaluates active and sealed results and reports uninspectable workspaces or artifacts as violations rather than silently treating them as compliant. For example:
State administration is explicit:
Inspection reads schema/version summaries without requiring supported records. Backup requires a new destination and copies durable manifests, results, patches, and policy, not live workspaces or Git repositories. Backup publishes backup.json last as its completion marker. An interrupted export or backup may leave a reserved destination without its completion marker; callers should treat it as incomplete and choose a new destination or remove it after inspection.
Rust API
use ;
let manager = open_default?;
let mut options = new;
options.label = Some;
let capsule = manager.create?;
// Launch any external tool with capsule.workspace_path as its cwd.
let status = manager.status?;
let result = manager.close?;
# Ok::
The crate owns lifecycle, provenance, artifact descriptors/streams, policy checkpoints, audit records, and state administration. The caller owns process launch, model choice, prompts, credentials, sandboxing, verification execution, and any remote artifact transport.
Guarantees in the first milestone
- Multiple attempts may start at the same immutable commit.
- Each receives a separate ordinary Git worktree and branch.
- Attempts may change the same files independently.
- The source worktree remains untouched until explicit integration.
- Every result has a complete patch, changed-path inventory, digest, sealed provenance, and discoverable artifact descriptors/streams, and its exported receipt verifies offline on any machine.
- Lifecycle transitions produce bounded structured audit events; aggregate metrics are available without a daemon.
- Repository and resource policy is enforced at core mutation boundaries and can be evaluated against current state.
- Results and journaled checkpoint, integration, and cleanup transitions survive process restart and can be inspected or recovered by another process or agent.
- Missing, replaced, drifted, or unrepresentable workspaces fail closed.
- Cleanup refuses foreign directories even with
--force. - Integration is explicit and requires a clean target at the exact pinned base.
- State can be inspected and backed up without a runtime-specific service; exported receipts can be verified with no state at all.
Scope
Capsule owns an attempt boundary, not work planning or agent orchestration.
It composes with issue trackers, agent runners, coding agents, workflow engines, and CI rather than replacing them. An external task ID can be attached with --link; no tracker is privileged or required.
See:
Status
This release intentionally supports Git repositories only and expects UTF-8 paths in result inventories. Sparse-checkout, skip-worktree, and assume-unchanged entries are rejected because an absent or hidden file cannot be distinguished safely from a requested deletion. Dirty nested submodule worktrees and unregistered embedded Git repositories are rejected rather than silently omitted or converted to accidental gitlinks; commit a registered submodule change first if the top-level gitlink should be captured. Ignored untracked paths are excluded from the patch but reported by status.ignored_paths and recorded — with byte count and content digest — in the sealed result as provenance; because ignored content is exactly what the repository declared irrelevant, its later churn (build output, caches, logs) does not invalidate the seal or block integration and cleanup. Remote execution, distributed persistence, background jobs, non-Git snapshots, automatic rebasing, merge queues, network services, signed attestations, continuous kernel-enforced quotas, and execution sandboxing remain out of scope.
The on-disk capsule/result schema is version 3. Incompatible state fails closed but remains inspectable and backupable; there is no schema migration before a first stable release.
License
MIT.