https://github.com/robzilla1738/arc-loop
Rust supervisor and plugin for Agent Run Contracts
https://github.com/robzilla1738/arc-loop
agent-contracts claude-code codex coding-agents rust
Last synced: 1 day ago
JSON representation
Rust supervisor and plugin for Agent Run Contracts
- Host: GitHub
- URL: https://github.com/robzilla1738/arc-loop
- Owner: robzilla1738
- License: mit
- Created: 2026-06-09T15:44:00.000Z (15 days ago)
- Default Branch: main
- Last Pushed: 2026-06-09T16:52:56.000Z (15 days ago)
- Last Synced: 2026-06-21T14:57:13.889Z (3 days ago)
- Topics: agent-contracts, claude-code, codex, coding-agents, rust
- Language: Rust
- Size: 79.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# 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:
```text
.agent/contracts//
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
```bash
git clone https://github.com/robzilla1738/arc-loop.git
cd arc-loop
cargo install --path .
```
You can also use the wrapper without installing:
```bash
bin/arc --help
```
## Quick start
Create a run:
```bash
arc new goal auth-refresh --title "Fix auth refresh"
```
Edit the generated files:
```text
.agent/contracts/auth-refresh/arc.toml
.agent/contracts/auth-refresh/prompt.md
```
Lint it:
```bash
arc lint auth-refresh --strict
```
Prepare a launch command:
```bash
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:
```bash
arc doctor --agent all auth-refresh
arc validate auth-refresh
arc status auth-refresh --json
arc report auth-refresh
```
Open the dashboard:
```bash
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:
```bash
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:
```bash
arc hook claude pre-tool
arc hook codex pre-tool
arc hook codex stop
```
If exactly one ARC run is active, `auto` selects it. If more than one run is active, set `ARC_CONTRACT=.agent/contracts/`.
## Documentation
- [Getting started](docs/getting-started.md)
- [Real use](docs/real-use.md)
- [Contract schema](docs/contract-schema.md)
- [CLI reference](docs/cli.md)
- [Enforcement model](docs/enforcement-model.md)
- [Hooks and plugins](docs/hooks-and-plugins.md)
- [Manual smoke tests](docs/manual-smoke.md)
- [Amendments](docs/amendments.md)
- [Examples](docs/examples.md)
- [Security notes](SECURITY.md)
## Development
```bash
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](LICENSE).