Claude Code / Codex / pi / Antigravity
Epoptes runs the long jobs you'd love to hand to an agent overnight: a feature build, a research sweep, a stack of documents, a data clean-up. You describe the goal in a chat. Epoptes runs it as a series of fresh-context cycles in a time box, with a live dashboard, a board you steer it through, and a report in the morning.
ἐπόπτης, “the overseer”: a title for Zeus and Helios, who watch over everything.
01 · what it is
Three small parts that share nothing but a folder of plain files, .epoptes/, in your project.
Any of them can be replaced, and you can read or fix every file by hand.
Ask your agent to “use the epoptes skill”. It interviews you about the outcome, a done definition it can check, the time box, the team and what always needs your approval. Then it writes the harness and checks it with a dry run.
A detached process per goal. Each cycle starts your own claude, codex,
pi or agy with a fresh context. The cycle orients from small state files and
the board, does a slice of work, verifies it, records it and exits.
epoptes ui on 127.0.0.1. A live ticker, a kanban board for feedback, approvals to answer,
the clock, costs and plan usage, then a report. Closing it never stops a run.
02 · why
Epoptes grew out of a 12-hour autonomous game build: 19 cycles, about $186 of API-equivalent usage, and a notebook of what went wrong. Its rules for keeping long runs cheap and on track are built in, so you don't have to relearn them.
One context fills up, gets summarised, and forgets what failed.
Memory lives in small files the next cycle reads first: a 25-line handoff, a progress table, lessons and decisions. Nothing drifts out of a summary, and every cycle starts sharp.
Every step costs the price of the most expensive model.
A team of roles, each with its own model: a strong orchestrator and reviewer, mid-size workers, and a small checker that only runs tests and reports facts.
Notes grow until reading them is the job.
Each state file has a line cap the dry run and the runner check. Orienting takes six tool calls or fewer, with targeted reads instead of whole files.
A single run can wander for hours with nothing to show.
A cycle does at most three rounds of one to three tasks, under a soft time cap and a hard timeout. A fresh cycle is cheaper than a bloated one.
03 · the night shift
The same 8-hour job, two ways: one agent session told to “keep going all night”, and an Epoptes harness. Drag the clock, or press play.
“Build the field guide. Keep going all night.”
working
The same goal, 8-hour time box, done checks agreed up front.
cycle 1
An illustration of the failure modes Epoptes was built around, not a benchmark. Your agent may do better on a good night.
| Ask one agent session | Run it with Epoptes | |
|---|---|---|
| Context | One window that fills, gets compacted and loses detail | A fresh context every cycle; memory in small, capped files |
| “Done” | When the agent says it looks good | Checks agreed at the interview: commands, files, a reviewer's rubric |
| “Shall I continue?” | Waits for an answer you're asleep for | The loop says what's next. Approvals wait while other work carries on |
| Time | No clock: it stops early, or runs on | A time box of active time, then wrap-up; it finishes early once checks pass |
| Closing the laptop lid | Ends the session | The runner is detached; the next start recovers interrupted work |
| Rate limits | An error, or a loop of retries | Waits for the reset with the clock paused, then carries on |
| Models | One model for every step | A model per role: small for checks, strong for review |
| Steering | Type into the session and hope it notices | Cards and comments on a board; ⚡ Steer now replans around you |
| Seeing the cost | A total at the end, if you ask | Tokens, cache share and cost per cycle, outliers flagged, plan usage live |
| The morning after | A long transcript | A report, the board, events, commits or snapshots per cycle |
| The next job | Starts from zero | Starts from the brain: lessons from every harness you've run |
04 · crash course
Seven steps. The first two take a few minutes; the rest is the run looking after itself.
You need Node.js 22.18 or newer, Linux, macOS or WSL2, and at least one agent CLI installed and logged in. Epoptes runs your own CLI and never handles logins or keys.
The skill is how your agent learns to design harnesses. Install it for each CLI you use: it links into that CLI's skills folder.
$ npm install -g @ramigbcom/epoptes
$ epoptes skill install # Claude Code
$ epoptes skill install --agent codex # Codex
$ epoptes skill install --agent pi # pi
$ epoptes skill install --agent antigravity # agyIn the folder the work should happen in, ask for a harness. The agent looks around first, then asks only what it can't find out, two to four questions at a time:
It reads lessons from your past harnesses and shows a one-screen summary for you to sign off.
> use the epoptes skill to build a harness for writing a
20-page field guide to our internal APIs
● I read the README, the OpenAPI spec and docs/. A few questions:
1. Done: how would you check it in 2 minutes?
❯ every endpoint documented + examples run (Recommended)
an editor's rubric score ≥ 8 as well
2. Time box: ❯ 8h active, 45m wrap-up (Recommended)
3. Team: ❯ writer (sonnet) · factcheck (haiku) · editor (opus)
4. Always ask before: ❯ publishing anything outside this machine
● Lessons applied from the brain: 2 (fresh-results timestamps,
parallel tasks own separate files). Summary below; sign off?
Everything lives in .epoptes/ next to your work. Commit it, diff it, edit it by hand. Live
runner state and per-cycle transcripts are gitignored and never leave your machine.
Role files become native subagents on Claude Code, Codex and Antigravity, each on its own model. On pi the loop works through them in sequence.
.epoptes/
goal.json objective, done checks, time box, models
loop.md the orchestrator's per-cycle instructions
agents/
writer.md model: sonnet · effort: medium
factcheck.md model: haiku · effort: low
editor.md model: opus · effort: high
settings.json allow/deny list: no git push, no .env
state/ handoff.md (25 lines), progress, lessons
board.jsonl every card, comment and move
events.jsonl milestones, blocks, done
cycles/ run/ per-cycle records · live state (ignored)
"done": [
{ "id": "D1", "check": "every endpoint has a page",
"verify": { "type": "command", "run": "npm run check:coverage" } },
{ "id": "D2", "check": "editor scores every chapter ≥ 8",
"verify": { "type": "agent" } }
],
"timebox": { "total_min": 480, "wrapup_min": 45, "grace_min": 30 }
epoptes run --dry-run never starts the clock. It validates the goal and prints the exact
command the next cycle will run. It also flags:
Then epoptes add registers the goal with the dashboard.
$ epoptes run --dry-run
goal field-guide: A 20-page field guide to our internal APIs.
adapter claude-code (2.1.300) · roles: writer, factcheck, editor
time box 8h00m (wrap-up 45, grace 30) · cycle timeout 90 min · checkpoints git
clock: not started (a dry run never starts it)
next cycle runs in ~/work/api-guide:
claude -p "<loop.md>" --model sonnet --effort medium --permission-mode auto
--agents …/agents.json --settings …/settings.json …
warnings:
state/lessons.md has 34 lines (cap 30)
ok with warnings
$ epoptes add
registered field-guide (API field guide)Open the dashboard and press Start, or start from the terminal. The runner is detached: closing the dashboard or the terminal never stops it.
Between cycles it checks the clock, your controls, rate limits and failures. Near the end the goal switches to wrap-up (feature freeze), then overtime, then stops. It finishes early once its checks pass.
$ epoptes ui
dashboard on http://127.0.0.1:4747
$ epoptes start field-guide
started: run r1, runner pid 48213
$ epoptes status
field-guide · API field guide (~/work/api-guide)
state running (pid 48213) · run r1 · cycle 7 · mode build
clock 2h41m active of 8h00m · wrap-up in 4h34m · end in 5h19m · …
pace M1 took 72% of its planned time · on pace to finish at ~6h50m of 8h00m
board 6/10 done · 1 backlog · 2 todo · 1 doing · 1 review · 0 blocked · 0 cut
last cycle c6: ok · 0h38m · 41 turns · ≈ $1.12 (estimate)Your feedback lands in the backlog as a card. The orchestrator triages it into TODO or cuts it with a reason, works it, verifies it in REVIEW and moves it to DONE. Comment on any card; the next cycle acts on it or replies.
Anything on the approval list waits for your Approve or Disapprove while the run carries on with other work. Need to change course right now? ⚡ Steer now interrupts the cycle, and the next one replans the board around you.
$ epoptes feedback "the intros are too long"
added C-9 to the backlog
$ epoptes card C-4 comment "link the error codes table"
$ epoptes card C-12 approve "internal wiki only"
$ epoptes feedback "drop GraphQL, REST only" --steer
added C-13 (steering): the running cycle is interrupted now
and a fresh one replans around it
$ epoptes extend 1h
$ epoptes pause # after this cycleThe report covers what was done, where the time went, tokens and cost per cycle, milestones against the plan, and the handoff. It comes as Markdown and as script-free HTML.
Small tweaks after DONE go through a follow-up: only your open cards, no time box. The project's next feature is a new job on the same harness, which keeps its roles and lessons. Every run feeds the brain, so the next harness starts smarter.
$ epoptes report
report written:
~/work/api-guide/.epoptes/reports/field-guide-20261029-0712.md
~/work/api-guide/.epoptes/reports/field-guide-20261029-0712.html
$ epoptes start --follow-up # fix my open cards
$ epoptes job new "SDK quick-starts"
$ epoptes brain
brain: 6 goals, 41 harness lessons, 9 signals
~/.epoptes/brain/INDEX.md05 · features
One kanban board per harness, each job an epic. Cards carry a milestone, a role and a priority. Drag them, comment on them; a comment on a done card reopens it.
Interrupts the running cycle. The next one replans the whole board around what you said. Works from a card comment too.
What's on the approval list waits for you while the run carries on. Only when nothing else can move does it pause as “waiting for you”, with the reason.
Counts active time only: pauses and rate-limit waits don't count. Wrap-up, overtime, early finish, and a projected finish from the milestone pace.
Two to six done checks: a command that exits 0, a file that must exist, a reviewer scoring against a rubric you wrote together. Few manual ones.
Roles run as native subagents on Claude Code, Codex and Antigravity: cheap models for checks, strong ones for review. On pi, any OpenRouter model.
Tokens by model, cache share and cost per cycle, with cycles over twice the median flagged. Plan usage live. Rate limits wait for the reset.
Code goals commit each verified task (never push). Anything else gets a shadow git snapshot after every cycle, outside your own repo.
Lessons from every run, plus each goal's numbers and signals, gathered locally for zero tokens. The skill reads them before designing the next harness.
One harness, many jobs over time. After DONE, a follow-up fixes your open cards in place, and flags anything big for a new run.
Markdown and script-free HTML that open from disk and print. “Where the time went” shows running, rate limits, waiting for you, per role and per tool.
Each CLI's own permissions or sandbox, no push, no secrets in goal files. The dashboard binds to 127.0.0.1, with CSRF and DNS-rebinding guards. No telemetry.
06 · bring your own agent
Epoptes runs the CLI you're already logged into, on your plan or your keys. A harness says which one in
goal.json; the dashboard, board and reports work the same for all four.
| Claude Code | Codex | Antigravity | pi | |
|---|---|---|---|---|
| Each cycle runs | claude -p | codex exec --json | agy -p | pi --mode json |
| Roles | native subagents | native custom agents | native subagents | worked in sequence |
| Model per role | haiku · sonnet · opus | any Codex model + effort | flash · pro · inherit | one per cycle |
| Permissions | allow / deny list | native sandbox and rules | agy's own allow rules | Epoptes deny-list guard |
| Cost shown | ≈ API-equivalent | tokens | tokens | ≈ from pi's catalog |
| Plan usage | 5h and 7d windows | 5h and 7d windows | — | API spend |
| Budget cap per cycle | yes | — | — | yes |
epoptes is
epoptes isn't
07 · start tonight
The example writes a small glossary in about 15 minutes, for well under $1 of API-equivalent usage. Then ask your agent for a harness of your own.
npm install -g @ramigbcom/epoptes
epoptes skill install
git clone https://github.com/ramigb/epoptes.git
cp -r epoptes/examples/glossary /tmp/glossary
epoptes add /tmp/glossary && epoptes start glossary
epoptes uiuse the epoptes skill to build a harness for <your goal>Works in Claude Code, Codex, pi and Antigravity once the skill is installed for it. Needs Node.js 22.18+ on Linux, macOS or WSL2.