ARC Loop

ARC Loop is a small Rust supervisor for coding agents.

It gives Codex and Claude Code a contract to work inside. Then it checks the work without trusting the agent's final message.

The important part is boring on purpose: arc owns the run state. Agents can claim they are done. Only arc validate can mark a requirement as verified.

What it does

ARC Loop turns a run into a directory:

.agent/contracts/<run-id>/
  arc.toml
  prompt.md
  state.json
  events.jsonl
  evidence/
  artifacts/
  proposals/

arc.toml is the machine-readable contract. prompt.md is the brief the agent reads. The other files are owned by the supervisor.

You get:

• TOML contracts with path and command policy
• hook adapters for Codex and Claude Code
• proof states that separate agent claims from verified evidence
• an amendment flow so agents cannot quietly rewrite the contract
• a terminal dashboard for active runs
• plugin packaging for Codex and Claude Code

This is not a sandbox. It is a lifecycle guard for cooperative agents. That distinction matters.

Install

git clone https://github.com/robzilla1738/arc-loop.git
cd arc-loop
cargo install --path .

You can also use the wrapper without installing:

bin/arc --help

Quick start

Create a run:

arc new goal auth-refresh --title "Fix auth refresh"

Edit the generated files:

.agent/contracts/auth-refresh/arc.toml
.agent/contracts/auth-refresh/prompt.md

Lint it:

arc lint auth-refresh --strict

Prepare a launch command:

arc launch --agent codex auth-refresh --print
arc launch --agent claude auth-refresh --print

arc launch does not start an agent. It activates the run, records the current contract hash, writes launch artifacts, and prints the command you should run.

Validate the work:

arc doctor --agent all auth-refresh
arc validate auth-refresh
arc status auth-refresh --json
arc report auth-refresh

Open the dashboard:

arc tui
arc tui --snapshot

Proof states

ARC Loop uses explicit proof states:

• Unproven: nothing useful exists yet.
• ClaimedByAgent: an agent said the item is done.
• Evidenced: a matching hook event exists.
• Verified: arc validate reran the verifier and it passed.
• Rejected: arc validate reran the verifier and it failed.

Agents can only create claims or evidence. They cannot verify themselves.

Command proofs run from the repo root, not from wherever you happened to call arc. They also have timeouts and write stdout/stderr files under the run's evidence/ directory.

Hook support

Claude Code can load this repo as a plugin:

claude --plugin-dir .

Codex loads the shared skill and bundled hook config from the plugin. Command hooks still need the normal /hooks trust review before they run.

Both adapters call the same supervisor:

arc hook claude pre-tool <id-or-auto>
arc hook codex pre-tool <id-or-auto>
arc hook codex stop <id-or-auto>

If exactly one ARC run is active, auto selects it. If more than one run is active, set ARC_CONTRACT=.agent/contracts/<id>.

Documentation

• Getting started
• Real use
• Contract schema
• CLI reference
• Enforcement model
• Hooks and plugins
• Manual smoke tests
• Amendments
• Examples
• Security notes

Development

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
scripts/smoke-claude.sh
scripts/smoke-codex.sh

The CI workflow runs the Rust checks and a v2 smoke test against a generated run. The smoke scripts are for local host-adapter checks.

License

MIT. See LICENSE.