# perpetuum โพ๏ธ
> Loop engineering for coding agents, done production-grade โ a
> perpetual-motion engine, not a thought experiment.
> ๐งฌ **What this actually is โ a Skill, not a script.** `perpetuum`
> ships as an [Agent Skill](https://skills.sh): a small set of
> architectural ideas, prompt templates, trigger patterns, and a
> handful of working examples. When you say "use perpetuum to do X",
> your coding agent picks the closest example, **rewrites the prompts
> and `trigger.sh` for your specific task in your own language**,
> confirms what's tunable with you, then launches. The bash and the
> prompts inside aren't fixed code โ they're starting points the
> agent edits to fit your case. That's why ~1 kLOC of plumbing ends
> up flexible enough for tasks as different as ML training sweeps,
> per-PR review, adversarial testing, and style polish: **the
> architecture is fixed, the implementation is generated to fit**.
## ๐ Why your `/goal` runs go nowhere
You've probably tried `/goal` in Claude Code or Codex, or wired up a
Ralph Loop. What happens, every time: either it runs for a few minutes
and just stops, or it drifts off the main thread and keeps needing you
to step in for decisions.
That's not perpetual. That's just "unattended for 20 minutes."
Designing a system that actually holds up โ instead of just wiring a
prompt to a scheduler โ is what people are starting to call **loop
engineering**. Most attempts at it stop at exactly this wall.
`perpetuum` is what lets your coding agent **actually keep running โ
truly, perpetually, until you tell it to stop.** It works while you
sleep, while you're at lunch, while you're on vacation. It needs no
synchronous human attention.
Think of it as letting your coding agent moonlight as your night-shift
coworker. You hand it a project, go to bed, come back to a stack of
commits and a short list of "hey, you need to decide this one" notes.
**Day after day, indefinitely** โ never interrupted, never blocking on
your reply. Like a steady, diligent collaborator who just keeps working.
There are **three specific reasons** today's autonomous-agent attempts
fail at "perpetual" โ and three corresponding mechanisms perpetuum
uses to fix each. **Click each one to expand for the full explanation
and an ASCII diagram:**
1. Vague goals, wide operating space โ the agent drifts off-target
`/goal`-style tools accept whatever sentence you typed as the goal
and give the agent unlimited interpretive freedom. With nothing
actively pulling it back to the main thread or vetting its mid-run
decisions, it wanders.
**โ perpetuum** requires the goal to be narrow and judgeable
before it starts, and in every round it explicitly separates
"where should we head next?" from "do this concrete piece of
work and check the result". Because the part that proposes the
work and the part that accepts it stay distinct, drift gets
caught and "fake progress" can't quietly accumulate.
```
Today (/goal, Ralph Loop): the goal sentence is open to interpretation,
agent roams a huge unconstrained space.
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ goal: "make this project better" โ user's one sentence, โ
โ no metric, no boundary โ
โ โ
โ start โ
โ โโโโบโโโบโโโบโโโฎ โ
โ โฐโโโบโโโบโโโบโโโฎ โ
โ โฐโโโบโโโบโโโบ โ off-target โ
โ โฐโโโบโโโบโโโบโโโบ โ
โ โฐโโโบโโโบโโโบโโโบ โ
โ โโ โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ boundary = the entire interpretive space; nobody steers,
agent goes wherever, however far
perpetuum: narrow goal (suitability gate) + plan + judge every cycle
โโโ suitability gate forces a narrow, judgeable goal up front โโโ
โ โ
โ ๐ plan โ๏ธ judge ๐ plan โ
โ (rechecks dir) (rejects fake) (rechecks dir) โ
โ โผ โผ โผ โ
โ start โ โ โ โ
โ โโโโบโโโบโโโโโบโโโบโโโบโโโบโโโบโโโโบโโโบโโโบโโโบโโโบโโโโโบโโโบโโโบโโโบโโบ โ
โ โ โ โ โ
โ pull back on-target reject fake explore new โ
โ progress direction (safely) โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Key: the boundary is intentionally narrow,
plan re-steers periodically, judge vetoes bad single steps.
```
2. No continuation mechanism โ one short run and you're done
`/goal` is single-session. Even the "infinite loop" variants are
blindly time-triggered, no concept of event or condition. But a
lot of "keep this going" work runs on events, not a clock โ
watching for new PRs and triaging them as they arrive, reacting
to alerts when they fire, scanning whenever the codebase changes.
The loop needs to span sessions, restarts, and respond to
different kinds of trigger.
**โ perpetuum** gives the loop a real continuation mechanism:
it can run on a fixed schedule, or wake up when something
outside changes (a new PR appears, a file is touched, an alert
fires), or react to incoming events. The same loop persists
across sessions, restarts, days โ pick whatever trigger matches
the work.
But a trigger that fires into an empty queue is just a heartbeat
with nothing to do โ perpetual *timing* isn't perpetual *substance*.
That's the other half of the mechanism, easy to miss: every cycle's
**explore** phase doesn't just recheck direction, it appends
newly-discovered work to `plan.md`'s Pending list โ new test angles,
new follow-ups, new edge cases the last cycle's result surfaced. So
execution both drains the queue and refills it in the same breath.
Without that, a trigger firing on schedule forever would just
rediscover an empty todo list a few cycles in and idle โ "still
running" but with nothing left to do.
```
Today: a /goal run is a one-shot. Done = ended.
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ start โโโโบโโโบโโโบโโโบโโโบ done/stuck โฎ โ
โ โฐโโโโ one-shot โโโโโฏ โ
โ โ
โ then what? nothing. โ โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ single segment on the time axis.
"Find more bugs forever", "watch for new PRs",
"react to alerts" โ impossible past the first run.
perpetuum: stitch "Problem 1's solution" across the time axis,
indefinitely, on whichever kind of trigger fits the work.
Triggers:
โฐ schedule ๐ conditional ๐จ webhook
(every N min) (poll external state) (event-driven)
โ โ โ
โผ โผ โผ
โโโโโโโโโโโโ sleep โโโโโโโโโโโโ sleep โโโโโโโโโโโโ sleep โโโโโโโโโโโโ
โ โบcycle 1โบโ โโโโโ โ โบcycle 2โบโ โโโโโ โ โบcycle 3โบโ โโโโโ โ โบcycle Nโบโ ...
โ (P1 solv)โ โ (P1 solv)โ โ (P1 solv)โ โ (P1 solv)โ
โ ratchet โโ โ ratchet โโ โ ratchet โโ โ ratchet โโ
โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ
โ โ โ โ
plan.md โโโ persisted โโโ persisted โโโ persisted โโโ persisted
Key: each cycle = a safe short segment (Problem 1's solution).
Concatenated, they form genuine "perpetual" work.
Triggers are how cycles know when to start:
schedule โ do it more, on a timer
conditional โ only run when external state changed
webhook โ only run on an external event
plan.md isn't just read each cycle, it's refilled: explore
adds new Pending items as fast as execute drains them โ
the trigger keeps *timing* perpetual, this keeps it *fed*.
```
3. Human-in-the-loop is a wall, not a sluice โ the first ambiguity freezes everything
Traditional loops have no way to keep going when they hit something
they can't decide alone. They guess wrong or stop and wait โ and if
you're not at the terminal, "wait" means dead.
**โ perpetuum** makes the human-in-the-loop interaction
asynchronous. When the agent hits something only you can decide,
it writes the question down (along with the concrete options it
considered) and keeps going on everything else; you answer in
your own time. You can also nudge the running loop with a new
instruction at any moment without stopping it. Nothing blocks on
you being at the keyboard.
```
Today: hit ambiguity โ stop and wait synchronously. Human asleep = dead.
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ start โโโโบโโโบโโโบโโโ โ ๏ธ "A or B?" โ
โ โ โ
โ โ wait for human โ
โ โผ โ
โ โฎ stuck โฎ stuck โฎ ... โ
โ โ
โ human is sleeping / out / busy โ task dies here โ โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
perpetuum: async channels keep the main loop progressing while
the human's input arrives whenever it arrives.
Main loop (always progressing):
cycle 1 โโโบโโโบ cycle 2 โโโบโโโบ cycle 3 โโโบโโโบ cycle N โโโบโโโบ ...
โ โ โ
โ ambiguous โ ambiguous โ judge rejects
โ โ write out โ โ write out โ a bad proposal
โผ โผ โผ โ no commit happens
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ escalations.md (agent writes; human answers โ
โ when convenient) โ
โ ## Open โ
โ - A / B / C ? โ
โ - Pick a naming convention โ
โ โ
โ ## Resolved (you fill in at your own pace) โ
โโโโโโโโโโโโโโโโโโโโโโโคโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โ you answered
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ inbox.md (you push instructions in) โ
โ ## Pending โ
โ - SKIP: postgres โ
โ - PRIORITIZE: PR #123 โ
โ - DIRECTION: focus on auth module โ
โโโโโโโโโโโโโโโโโโโโโโโคโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ
โ next cycle's explore phase reads & applies
โผ
cycle N+1 โโโบโโโบ ...
Key: ambiguity โ goes to a queue (loop keeps going)
off-track step โ judge rejects it; no commit happens
human-not-there โ that's fine, the loop is async by design
```
The three solutions multiply: every cycle stays on-target (P1), the
time axis extends across triggers and restarts (P2), human input
arrives async without freezing anything (P3). Together that's what
"actually perpetual" means in practice.
## ๐ฆ Installation
Install using [`npx skills`](https://skills.sh).
### Install to all supported agents
```bash
# Global โ available in all projects, all supported agents
npx skills add zc277584121/perpetuum --all -g
# Project-level โ current project only, all supported agents
npx skills add zc277584121/perpetuum --all
```
Install to a specific agent
```bash
npx skills add zc277584121/perpetuum -a claude-code -g
npx skills add zc277584121/perpetuum -a codex -g
npx skills add zc277584121/perpetuum -a cursor -g
```
Other supported agents include `windsurf`, `github-copilot`, `cline`,
`roo`, `gemini-cli`, `goose`, `kilo`, `augment`, `opencode`, and
[40+ more](https://skills.sh).
> **Project vs Global**: Without `-g`, the skill installs into the
> current project for the selected agent. With `-g`, it installs
> globally and is available across projects.
You also need `tmux` and `git` available locally.
Then in any project, ask your coding agent:
> Use perpetuum to run continuous adversarial testing on this project
> for the next couple of days.
## ๐๏ธ Architecture
Four layers, each tied to one of the three problems above. Read the
right-side tags first โ they're the whole point.
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ๐๏ธ Layer 4 you + host agent (Claude Code / Codex) โ
โ describe the task, nudge it, pause, resume, stop โ
โ โ all in natural language โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ launches
โผ
โป โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโบ solves P2
โป โ โฐ Layer 3 trigger โ heartbeat, loops every cycle โ "no continuation":
โป โ schedule | conditional | webhook โ time, event, or
โป โ keeps running until you stop it โ condition keeps
โป โโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ the loop alive
โ kicks off next cycle
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโบ solves P1
โ ๐ง Layer 2 middle agent โ judge + dispatcher โ "agent drifts":
โ โ narrow goal
โ ๐ EXPLORE โ + plan / judge
โ re-read state ยท re-check direction โ split keeps
โ queue the next pending items โ work on-target
โ โ
โ โ๏ธ EXECUTE โ
โ for each pending item: โ
โ dispatch to Layer 1 โโโบ โ
โ judge the report: โ
โ โ
pass โ record + commit โ
โ ๐ bug โ fix + commit โ
โ โ ambig โ queue for human (no block) โโโผโโโบ solves P3
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโฒโโโโโโโโ "human is a wall":
โ dispatch โ report ambiguity goes
โผ โ to an async queue,
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโ loop keeps going
โ ๐ค Layer 1 inner agent โ fresh context, zero priors โ
โ runs the operation, observes, reports back โ
โ no memory of past cycles โ can't self-certify โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
Layer 4 is optional โ you can drive the state files directly. The
host agent is just a friendlier UI on top of the same file contracts.
## ๐ฎ Using It
After installation, perpetuum is a normal skill. From your coding
agent's TUI, name it explicitly and describe what you want it doing
overnight (or longer):
๐ **Adversarial bug-hunting on a CLI tool**
```text
Use perpetuum to run continuous adversarial testing against this CLI
for the next 30 cycles. Categories I care about: auth, parser, error
paths. Open A/B/C when a failure mode is ambiguous.
```
๐ฅ **GitHub issue triage on a busy repo**
```text
Use perpetuum to watch this repo's GitHub issues and triage new ones
every hour. Tag them, suggest labels, escalate only the ones that
need a product decision.
```
๐๏ธ **Observability gap discovery in a service module**
```text
Use perpetuum to keep finding observability gaps in the worker module
for ~20 cycles, then stop and let me review. Commit each gap-fix as
a separate commit so I can cherry-pick.
```
โ๏ธ **Style transfer toward a target author's voice**
```text
Use perpetuum to iteratively polish this draft article toward
Karpathy's writing style. His articles are in target_corpus/. Use BLEU
+ readability + a stylistic-similarity LLM judge as the metric. Stop
when the metric plateaus for 5 cycles.
```
๐งช **ML hyperparameter sweep / overnight training run**
```text
Use perpetuum to keep training this LoRA overnight. Each cycle, pick
one hyperparameter to vary (lr, rank, dropout, batch size), kick off
a short training run, eval on the val set, record val loss + a sample
generation. Stop after 50 trials or when val loss hasn't improved for
10 cycles. Commit one row to results.csv per trial. Cap each
hyperparameter's range up front and keep the val set off-limits to
the loop โ that's how this kind of sweep avoids local-optimum
dead-ends and metric-hacking shortcuts.
```
๐ฆ **CI failure triage on the main branch**
```text
Use perpetuum to watch CI on the main branch. When a build fails,
diagnose, propose a fix, commit it to a fix/ branch, and
open a PR. Don't push to main directly. Run on the webhook trigger.
```
๐ **Per-PR security risk review**
```text
Use perpetuum to comb every PR in this repo for security-relevant
diffs (auth, secrets, network). For each PR write a one-paragraph
risk note. Run on the conditional trigger โ only spin up when a new
PR arrives.
```
๐ **Long, mechanical migration across a large codebase**
```text
Use perpetuum to migrate every call site of `old_api.call(...)` to
`new_api.call(..., context=...)` in this repo. One module per cycle:
read it, edit the call sites, run that module's tests, commit. Skip
test files for now. Open A/B/C if a call site has non-trivial
side-effect semantics.
```
After you describe a task this way, the skill walks you through a
short back-and-forth โ what "done" looks like for your case, how
often to run, where to commit, which decisions to auto-make vs
escalate โ and only launches once both sides agree. The first
message is a request; the actual config is nailed down in that gate
before any cycles burn tokens.
The list above isn't exhaustive. **Anything that fits the criteria
below โ narrow goal, judgeable signal, many small steps, etc. โ is a
candidate, even if it has nothing to do with code:** literature
reviews that compound over days, dataset curation, slow translation
of a large doc, long-form prompt tuning, anything where "a little
more, every hour" is what you want.
### Why these tasks fit
The pattern they share:
- **A clear, narrow goal**, not "make this project better". *e.g. the
adversarial example names auth / parser / error paths; the ML sweep
names which 4 hyperparameters to vary; the migration names one
exact call-site pattern.*
- **A judgeable signal** โ pass/fail, a number that moves, a diff
someone can review. Without one, the ratchet has nothing to ratchet
on. *e.g. CI watcher uses build status; ML sweep uses val loss;
style polish uses BLEU + LLM judge; migration uses module-level
test pass.*
- **Many small steps**, not one big atomic delivery โ perpetuum's
advantage compounds over cycles. *e.g. 30 adversarial cycles, 50
hyperparameter trials, one PR scanned per arrival, one module
migrated per cycle.*
- **Tolerance for the inner agent being wrong sometimes** โ the
outer judge catches it, but if a single wrong step is catastrophic
(e.g. deploying to prod), this is the wrong tool. *e.g. the CI
watcher fixes go through a PR, never `git push` to main; migration
commits are per-module, easy to revert.*
- **Either the work itself takes a long time, or you want to do a
small step many times over many days.** A 10-minute task doesn't
need perpetuum; a 10-cycle task across a long weekend does. *e.g.
ML sweeps span overnight, PR review compounds as PRs arrive over a
week, migration may take days of small commits.*
### When it's the wrong tool
Don't reach for perpetuum if:
- **One-shot tasks.** "Rename this function across the codebase",
"write a regex for this log format" โ these are single steps, not
loops. Use `/goal` or a normal coding session.
- **The goal isn't judgeable.** "Make this UI look nicer", "rewrite
this in a more elegant way" with no concrete criterion. Without
something Layer 2 can grade, fake progress is indistinguishable
from real progress.
- **Every step needs synchronous human input.** Pair-programming on
a new feature, exploring a design space together โ the whole point
of perpetuum is that you're *not* at the terminal. If you would
be anyway, just talk to your coding agent directly.
- **Irreversible actions on every step.** Sending emails to real
users, hitting production APIs that charge money, deleting data.
perpetuum's ratchet is local โ it can roll back a commit, not an
email or a charge.
- **You need the answer in the next 10 minutes.** perpetuum trades
wall-clock time for unattended time. If you're waiting, you're
using it wrong.
### While it's running
Once launched, the task is a black box. You don't need to know which
layer is doing what; you only need to know which **kinds** of operations
you can send in, and what comes out.
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ โซ a perpetuum task running โ โโโบ ๐ git commits
โ (the loop, hidden) โ (the actual work)
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โฒ โฒ โฒ โฒ
โ โ โ โ
โ๏ธ nudge ๐ฌ answer โธ๏ธ pause ๐ watch
push new resolve โถ๏ธ resume read-only
direction open A/B/C ๐ stop progress
or skips questions feed
โฒ โฒ โฒ โฒ
โ โ โ โ
โโโโโโโโโโโโดโโโโโโฌโโโโโโดโโโโโโโโโโโ
โ
all in natural language
โ
โผ
๐ค you โโโบ ๐๏ธ host agent (Claude Code / Codex / โฆ)
"perpetuum, focus on auth this week"
"the off-by-one question โ go with option B"
"pause until I've looked at the last few commits"
"what's it working on right now?"
"stop after the current cycle"
```
The host agent translates your sentences into the underlying file
operations. You never have to remember a flag name or a file path โ
if you can describe the change in plain English, you can drive the
loop.
## ๐งฌ Design philosophy
The three core problems above are what perpetuum solves. To solve
them it leans on nine deliberate design choices โ each individually
well-known, none combined like this in prior art. These are the
same nine axes the comparison table below scores every project on,
in the same order.
1. **Ralph Loop, generalized โ the heartbeat that keeps things
moving.** The original [Ralph Loop](https://ghuntley.com/loop/)
is the simplest possible "keep moving" engine: a `while true` in
a shell script that re-prompts the agent over and over. That
infinite-loop instinct is the raw driving force behind anything
"perpetual" โ without it, you get one response and you stop.
perpetuum's Layer 3 is that same heartbeat, but generalized to
three trigger families instead of just one: **schedule** (the
Ralph default โ every N minutes), **conditional** (poll an
external state like `gh pr list` and only fire on real change),
**webhook** (react to incoming events). Same Layer 2 / Layer 1
stack behind all three. This is what lets one skill cover both
"spin up every hour" and "spin up when a PR arrives" without
rewriting the inner loop.
2. **Discriminator / Generator separation** (from GANs). Layer 2 is
the discriminator โ it sees the entire history, judges every
proposal, but does not run code itself. Layer 1 is the generator โ
fresh context every dispatch, runs the actual operation, has no
memory of what came before. Because they share no context, neither
can fake a result the other would accept. This is what kills the
self-certifying failure mode in `/goal` and Ralph Loop, where the
same agent both produces and grades โ over a long run, that
collapses into "everything is fine, keep going".
3. **Asynchronous human escalation โ the thing that makes "perpetual"
actually perpetual.** When Layer 2 hits an ambiguous decision
(off-by-one semantics, naming convention, product call) it writes
A/B/C options to `escalations.md ## Open` and **moves on to the
next item in the same cycle**. The human answers later, whenever
convenient. The loop never blocks waiting for a reply. Without
this, the first hard question you hit while you're asleep stops
the whole engine until you wake up; with it, the loop runs through
the night, builds a small queue of decisions waiting for you, and
keeps producing on everything that isn't blocked. This is the
single feature most other autonomous-loop projects don't have, and
it's the difference between "runs unattended for 20 minutes" and
"runs unattended for a week".
4. **Monotonic ratchet** via local `git commit`. Layer 2 judges every
Layer 1 proposal *before* it becomes a commit โ rejected ones
never enter history. Accepted ones land as a clean append-only
sequence on the branch, and `git log` doubles as the durability
mechanism across sessions, machines, and reboots. Without a
ratchet, you can't tell progress from noise on a long run.
5. **Exploration vs Exploitation split** at the prompt level.
Phase 1 (`prompts/1_explore.md`) is divergent โ re-read state,
re-check direction, queue new pending items. Phase 2
(`prompts/2_execute.md`) is convergent โ work down the queue,
one item at a time, commit or escalate. Fusing them into one
prompt is what makes long Ralph-style runs drift โ but it's also
what keeps the run *perpetual* in substance, not just in timing:
Phase 1 adds to `plan.md`'s Pending list every cycle, Phase 2
drains it, so the backlog is replenished as fast as it's consumed
instead of running dry a few cycles into a long trigger schedule.
6. **File-based persistent memory, no vector DB required for the
loop's own state.** plan / inbox / escalations + the git log are
the entire memory system Layer 2 needs to keep the loop itself
running โ this working set is small enough to re-read in full
every cycle, so it never needs an embedding store. Layer 2
re-reads these files at the start of every cycle, so context rot
stays bounded and state survives any restart โ pause at noon,
resume at midnight, next cycle picks up exactly where the last
one left off.
If you want the explore phase to also draw on a much larger pool
of history โ this person's past decisions and style across other
work, not just this loop's own backlog โ that's a different,
optional layer. A memory-search tool with vector retrieval (e.g.
[MemSearch](https://github.com/zilliztech/memsearch)) can plug in
alongside the file-based core for that, not instead of it.
7. **Architectural decoupling and responsibility separation.** Each
layer owns one well-defined job: Layer 3 owns "keep ticking",
Layer 2 owns "judge and dispatch", Layer 1 owns "do one bounded
piece of work in fresh context". **Inside** each layer the
implementation is freely swappable โ Layer 3 could be `trigger.sh`,
cron, a GitHub Actions runner, or a Lambda; Layer 2 could be
Claude Code, Codex, Cursor, or another coding-agent TUI; Layer 1
could be any `cc-use`-supported agent. The interfaces between
layers (file state, tmux paste, and named cc-use sessions) are what
stays stable; everything else is interchangeable. This is why the same
small skill stays lightweight yet handles wildly different
scenarios โ the **architecture is the contract**, the pieces inside
are not.
8. **File-as-contract.** Who can edit which file is a convention,
not enforced by code: agent owns `plan.md`, human owns `inbox.md`,
both touch `escalations.md` at different sections. Cleaner than
role-based access control, debuggable with `cat`, mergeable with
`git`.
9. **Host-agnostic dispatch, no vendor lock-in.** Because perpetuum
ships as an [Agent Skill](https://skills.sh) โ a few hundred lines
of bash plus prompt templates, not a service or a framework โ it
stays **lightweight and host-agnostic by construction**. The
actual coding agent is loaded at runtime via
[`cc-use`](https://github.com/zc277584121/cc-use), which speaks
Claude Code, Codex CLI, Cursor, Windsurf, Gemini CLI, Goose, and
40+ other coding-agent CLIs. A task started in one host can be
picked up later in another, because nothing in the skill is bound
to a specific agent's SDK, API, or proprietary protocol โ the
state is just files on disk. **No vendor lock-in.** This matters
because coding agents move fast โ flags get renamed, pricing
changes, models deprecate. You don't want your "always running"
infrastructure to die the day your preferred CLI ships a breaking
change.
Removing any one of these breaks something. See
[`skills/perpetuum/references/design.md`](skills/perpetuum/references/design.md)
for the long-form rationale on each.
## ๐ Loop engineering: comparison with related projects
| Project | trigger abstraction | disc/gen split | async human | ratchet | explore/exploit split | persistent memory | multi-layer | file contract | Claude+Codex |
|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| Claude Code [plan mode](https://code.claude.com/docs/en/plan-mode) | โ | โ | โ | โ | โ ๏ธ | โ | โ | โ | โ |
| Codex `/plan` mode | โ | โ | โ | โ | โ ๏ธ | โ | โ | โ | โ |
| Claude Code [`/goal`](https://code.claude.com/docs/en/goal) | โ | โ ๏ธ | โ | โ | โ | โ | โ | โ | โ |
| Codex [`/goal`](https://github.com/openai/codex) | โ | โ | โ | โ | โ | โ ๏ธ | โ | โ | โ |
| Claude Code [`/loop`](https://code.claude.com/docs/en/scheduled-tasks) | โ ๏ธ | โ | โ | โ | โ | โ ๏ธ | โ | โ | โ |
| [`goalbuddy`](https://github.com/tolibear/goalbuddy) | โ | โ | โ | โ ๏ธ | โ ๏ธ | โ
| โ | โ
| โ
|
| [`OpenSpec`](https://github.com/Fission-AI/OpenSpec) | โ | โ | โ | โ | โ ๏ธ | โ
| โ | โ
| โ
|
| [Ralph Loop](https://ghuntley.com/loop/) | โ | โ | โ | โ | โ | โ ๏ธ | โ | โ | โ ๏ธ |
| [`loop-engineering`](https://github.com/cobusgreyling/loop-engineering) | โ
| โ ๏ธ | โ ๏ธ | โ | โ ๏ธ | โ
| โ ๏ธ | โ | โ
|
| [`recursive-improve`](https://github.com/kayba-ai/recursive-improve) | โ | โ | โ | โ
| โ | โ ๏ธ | โ | โ | โ |
| [Karpathy AutoResearch](https://github.com/karpathy/autoresearch) | โ | โ | โ | โ
| โ | โ
| โ | โ
| โ |
| [Darwin Gรถdel Machine](https://arxiv.org/abs/2505.22954) | โ | โ | โ | โ
| โ | โ | โ | โ | โ |
| [EvoSkills](https://arxiv.org/abs/2604.01687) | โ | โ | โ | โ
| โ ๏ธ | โ ๏ธ | โ | โ ๏ธ | โ |
| [`nuwa-skill`](https://github.com/alchaincyf/nuwa-skill) | โ | โ ๏ธ | โ | โ | โ ๏ธ | โ ๏ธ | โ | โ | โ
|
| **`perpetuum`** (this) | โ
| โ
| โ
| โ
| โ
| โ
| โ
| โ
| โ
|
`perpetuum` is the only one with every column checked โ the
combination is the point.
## ๐ Updating
```bash
npx skills check # what's stale?
npx skills update # update everything globally installed
```
To update a project-level install, re-run the `npx skills add` command.
## ๐ Dependency: `cc-use`
`perpetuum` requires the [`cc-use`](https://github.com/zc277584121/cc-use)
skill โ Layer 2 uses it to dispatch every unit of work to a
fresh-context inner agent. The skill checks at init time and prompts
you if missing:
Each logical Layer-1 dispatch uses a unique session name. Readiness checks,
task delivery, monitoring, and follow-up guidance stay in that session until
Layer 2 judges the result, then the session is closed. Separate items and blind
judges use separate names.
```bash
npx skills add zc277584121/cc-use --all -g
```
If you haven't used `cc-use` before, its README is the prerequisite
read.
## ๐ License
MIT โ see [LICENSE](LICENSE).