Apron Agents

A local, one-command tool that breaks a coding task into small independent issues, hands them to worker agents that each work in an isolated sandbox, and merges their work one chunk at a time behind a human review gate.

The name comes from the airport apron: the staging area where aircraft are prepped and checked before they ever reach the runway. Apron Agents does the same with code before it reaches your real remote.

How it works

• An orchestrator agent splits your task into small, file-independent issues.
• Worker agents each claim an issue and work in an isolated clone of a disposable, fully local sandbox repository (a bare repo in a temp dir acting as a "fake GitHub"). Your real remote is never touched.
• A merge controller merges one branch at a time, running tests on every candidate merge.
• A dashboard gives you a live view of every agent plus a chunk-by-chunk review-and-merge control surface. In supervised mode, nothing merges without your approval; in autonomous mode, green tests are enough.
• When everything is merged and green, the final result is copied into your working directory and the tool stops. You test locally and run any real git operations yourself.

Install

pip install apronagents

Then, from the project directory you want the agents to work on:

apron start

This boots the orchestrator, workers, merge controller, and dashboard server, and opens the dashboard in your browser. Enter a task, review the diffs, and approve merges chunk by chunk; when everything is green the result lands in your working directory and the tool stops.

No account? Try the whole flow with fake agents:

apron start --runner demo

Commands

apron start — boot everything and open the dashboard

apron start                          # supervised, auto-detected runner, current dir
apron start "add dark mode"          # dispatch this task as soon as apron is up

apron task — dispatch to a running apron from your terminal

apron task "add dark mode"                 # dispatch a task
apron task "add dark mode" --follow        # ...and narrate the run right here
apron task --from-issue 42                 # dispatch a GitHub issue of this repo
apron task --from-issue 42 --from-issue 43 # several issues as one task

apron report — run history and shareable reports

apron report            # list past runs of this project
apron report 8a645bde   # print one run's markdown report (a unique prefix works)

The report is the run's full audit trail — the task, the plan and whether it passed the plan gate, every review with its send-back reasons and line notes, what merged when, and exactly which files the handoff copied. Pipe it into a file or paste it into a PR.

Every setting is also an environment variable: APRON_MODE, APRON_RUNNER, APRON_WORKERS, APRON_PORT, APRON_TEST_COMMAND, APRON_SESSION_CONTEXT=1.

Quick start from a clone

For hacking on Apron itself:

git clone https://github.com/Ut8v/apronagents && cd apronagents
./run start

This sets up the environment with uv and launches everything the same way.

Agent backends

Workers run on whatever you already use — pick with --runner or let auto-detection choose:

Any other headless agent CLI can be plugged in as a CliProfile (src/apron/workers/cli_runner.py).

Customizing agents

Agent behavior lives in editable markdown definitions, not code. Apron ships defaults, discovers your existing .claude/agents/ definitions read-only, and writes any edits you make in the dashboard to a .apron/ overlay that hot-reloads on the next issue.

Contributing

See CONTRIBUTING.md — setup, workflow, and the invariants every change must respect. CI runs the test suite (Python 3.11–3.13), the dashboard typecheck/build, and a wheel install smoke test on every push and pull request.

License

MIT