Run a long refactor as a series of unattended agent sessions that you can actually review.
One plan, split into phases. One phase per headless run, on its own git branch, one commit per task, gates green before every commit. The runner survives usage limits, pins the conversation so your answers reach the right session, prints what the agent is doing while it does it, forecasts when the sequence ends, hands every new agent the lessons the earlier ones verified, and runs each task on the model that suits it, Claude's through Claude Code or Gemini's and others through Google Antigravity.
It exists because "let the agent go and see what happens" produces a diff nobody can read and a repository nobody can revert. The unit of trust here is the commit, not the session.
phasekit dashboard -Watch during a real run: 37 of 46 targets done, the forecast end and
the usage allowance it is planned against. phasekit logs -Follow shows, line by line, what
the agent is doing.
Contents. Requirements · Install · Quickstart · Writing the plan · Commands · Unattended sequences · How far along · Configuration · How much to verify · Lessons · Review and fix rounds · Antigravity models · Many models, one plan · What a target costs · What makes it work · Sources · Related projects
It is not a framework, an orchestrator, or a way to avoid thinking about your codebase.
The plan is the product; phasekit is the thing that presses play and refuses to let a
bad run look like a good one.
- PowerShell 7+ (Windows, macOS or Linux)
claudeonPATH(Claude Code)- git
Running phases, verifying, merging, waiting out usage limits, detaching and following logs work the same everywhere. Two things are the operating system's to provide, and phasekit uses whatever is there:
| Windows | macOS | Linux | |
|---|---|---|---|
| Keep the machine awake during a long wait | SetThreadExecutionState |
caffeinate -s |
systemd-inhibit |
| Notify when a sequence ends or stops | sound + tray balloon | afplay + osascript |
terminal bell + notify-send |
Neither is required. If the mechanism is missing, phasekit says so once and carries on — a machine with no notification daemon must not take a run down, and a run that cannot prevent sleep is still a run. The terminal bell is the fallback everywhere, which is also the one that survives ssh.
The whole test suite runs on all three, on every push (the badge above).
It drives phasekit auto end to end against a fake claude (tests/fake-claude), so
reviews, fix rounds, lessons and the plan check are exercised on each platform without an
account.
tools/resume-at-logon.ps1 and tools/watchdog.ps1 register Windows Task Scheduler
tasks. Elsewhere they refuse and print the launchd, systemd or cron equivalent to set up
by hand.
git clone https://github.com/<you>/phasekit.gitThen either call it by path, or add a function to your PowerShell profile
($PROFILE) so phasekit works anywhere:
function phasekit { & "C:\path\to\phasekit\bin\phasekit.ps1" @args } # Windows
function phasekit { & "$HOME/phasekit/bin/phasekit.ps1" @args } # macOS, Linuxcd my-project
phasekit draft # an interview that writes the plan, the prompts, the rules and phasekit.json
phasekit lint # the plan checked mechanically
phasekit gates # the gates actually run
phasekit auto -Detach # go; follow it with phasekit dashboard -WatchOr by hand: phasekit init writes the four files from the templates. Then edit
phasekit.json (the gates: the exact commands that must be green before every commit),
write PLAN.md in English (see docs/method.md and
docs/writing-a-plan.md) and the blocks in PROMPTS.md, and run
phasekit lint, phasekit gates and phasekit run 0.
The plan decides how good everything after it is, and it is the hardest part to write.
phasekit draft opens an interactive Claude session in the project that does it with
you. It reads phasekit's own guides and templates, audits the code if there is any (read
only, with evidence for every finding), then interviews you: a few questions at a time, each
with options and its recommendation, about the goal, the scope, the gates, the invariants,
the order of the phases, the decisions only you can make, and how unattended the run should
be (review, fix rounds, verify mode, models per task). Then it writes PLAN.md,
PROMPTS.md, AGENT-RULES.md and phasekit.json in phasekit's format, runs
phasekit lint until it is clean, and shows you the outline. It changes nothing that
exists without your yes, and it does not start the run. -Text "…" gives it a first
description of what you want.
It talks in whatever language you write in, and writes the files in English: the agents that execute the plan read English instructions and write English code and commits, and a plan in another language makes every session translate (why). Strings a user of your product will see stay in their language, quoted verbatim.
phasekit lint checks the plan with no model involved, for the mistakes that otherwise
surface hours into an unattended night: a ledger row with no task section, a task with no
ledger row or no "Done when", a target listed twice or unknown to the plan, an unticked
task the sequence never reaches, the template's placeholder gate. It reads only the markers
phasekit itself reads (### <id> headings, - [ ] <id> ledger rows, the prompt blocks,
phasekit.json), so a plan written in another language checks out too: name its own label
for "Done when" in "planSections". A numbered chapter of the plan ("### 1.1 The gates")
is not mistaken for a task.
phasekit auto runs the same check before it starts and refuses a plan with errors, with a
stop note that lists them ("lintBeforeAuto": false turns that off). Warnings never stop
anything.
| Command | What it does |
|---|---|
phasekit draft [-Text "…"] |
An interactive session that interviews you and writes the plan in phasekit's format (details) |
phasekit lint |
Check the plan mechanically: ledger, task sections, sequence, gates |
phasekit init [-Force] |
Scaffold the four files into the current directory |
phasekit run <phase> |
Create plan/phase-<n>, send the phase block, stream the run |
phasekit reply <phase> -Text "…" |
Answer a question in the same conversation |
phasekit reply <phase> -File answer.txt |
The same, from a file — easier to edit, survives shell quoting |
phasekit continue <phase> |
Pick up an interrupted phase where it stopped |
phasekit status [<phase>] |
Branch, dirty files, commits on the phase, ledger vs git log |
phasekit dashboard [-Watch] |
How far along, what is running, roughly how much is left |
phasekit steps [<phase>|<target>] |
What every phase and target is, in the plan's own words |
phasekit spend |
What each target cost: requests, peak context, one weighted number |
phasekit forecast [-Json] |
When the sequence ends, with the five-hour and weekly limits and their resets |
phasekit gates |
Run the gates yourself, no agent, no cost |
phasekit auto [-Push] |
Walk autoSequence unattended: run, verify, merge, next |
phasekit logs [-Follow] [-Full] |
Follow the run, rolling over to each new phase's log (and the reviewer's). One line per action by default; -Full shows whole commands with their purpose, the edits (lines removed and added), the head of every tool's output, errors in red, and when the model is thinking. What it thinks is not shown: headless runs record only that it did |
phasekit pause |
Stop the sequence now, process tree and all, and keep it stopped across reboots and the logon task (details) |
phasekit resume |
End a pause: the target it stopped on carries on in the same conversation |
phasekit account [<name>|next] |
List the Claude accounts on this machine, or switch the one runs use — a run waiting out a limit resumes at once (details) |
phasekit lessons |
What the agents learned so far, best first (details) |
phasekit lessons add -Text "…" |
Record one by hand: when <condition> | <lesson> | evidence: <what shows it> |
phasekit lessons drop <id> |
Retire one by hand; -Text says why |
phasekit review <target> |
An independent, read-only review of a target's branch as it stands (details) |
phasekit models |
Which model and effort each target runs on, and why (details) |
Useful flags: -Detach (survives closing the terminal), -DryRun (print the prompt and
the exact claude command, run nothing), -Watch (redraw the dashboard), -NoBranch,
-Model, -Effort, -MaxRetries, -WaitMinutes.
-Detach then hands the terminal straight back to following the run, so one command both
starts it and shows it. Ctrl+C there stops the following; the run is a separate process
and carries on. -NoFollow leaves you at the prompt instead, and phasekit logs -Follow
reattaches whenever you want. The follower rolls over on its own as each phase opens its
own log, and ends when the sequence does.
phasekit auto walks a list of targets on its own: run, verify, merge, next. The list
lives in phasekit.json, and each entry may name its own model — the cheap one where the
gates fully cover the change, the expensive one where a mistake would be silent:
"autoSequence": [
{ "target": "4.2", "model": "sonnet", "note": "mechanical move, fully covered by tests" },
{ "target": "4.3", "model": "opus", "note": "riskiest task in the plan" },
{ "target": "7.2", "effort": "medium" }
]model and effort are not the same lever, and the difference decides which one you
can actually use. A different model writes differently. On an isolated mechanical task
nobody minds; across half a codebase it reads as two authors, and on a product one person
will review end to end that is a real cost. The same model at lower effort thinks less
about the same problem and still writes in one voice.
So: the cheap model where the output is not code somebody will later copy the style of —
a CI workflow, generated types, baseline screenshots — and lower effort where the code is
product code but the task contains no decisions. Both default to the values at the top of
phasekit.json, and -Model / -Effort on the command line set the default for one run
without touching what an entry asks for by name.
phasekit dashboard prints what the sequence is spending and names every target that
differs from it, because an unexplained difference in the finished code usually traces
back to one of these two lines.
It stops at the first target that needs a person and writes the reason to
auto-stopped.txt. Skipping ahead would build every later target on top of something
nobody looked at — and unlike a human, an unattended loop would never notice. A target
that is already ticked and merged is skipped, so rerunning after a stop picks up where
it left off.
Leave irreversible steps out of the sequence and run them by hand.
One stop is not a question, and that one it answers itself. A task that ends its turn while a suite is still running in the background takes the suite down with it and leaves the branch dirty with no commits on it — every time, the fix is the same sentence, typed by hand at whatever hour somebody notices. So the runner types it: one reply into the same conversation, telling it to run the gates in the foreground and commit, and then it carries on. Once per target. If the same target comes back a second time the answer was not what it needed, and that stop is the honest one.
That is the whole of what it will answer for itself. Work on disk is what makes it recoverable, so a clean tree with no commits still stops — the reason a target produced nothing is exactly what nobody has established yet — and so does a missing branch, the wrong branch, or a ledger that disagrees with the repository.
It tells you when it ends, either way — sound and a desktop notice on both the completion
and the stop. The stop is the one that pays for it: a sequence waiting for an answer costs
nothing to fix and everything to not notice. Set "notify": false to turn it off.
Everything above survives inside the running process. Nothing inside a process survives that process dying, so a reboot is the one interruption the runner cannot handle on its own:
tools/resume-at-logon.ps1 -Install -Push -Config path\to\phasekit.jsonThat registers a logon task which resumes the sequence, and does nothing once it has finished. Resuming is safe to repeat: merged targets are skipped, and a target with a pinned session is continued rather than restarted.
A reboot is not the only way a process dies, though, and a logon task only helps if somebody logs on. Nobody does that over a weekend, so a run left alone wants the other half as well:
tools/watchdog.ps1 -Install -Push -Config path\to\phasekit.jsonThat asks every quarter of an hour whether the runner is still there, and restarts it only if it was killed. It can tell the difference because a sequence that finished and a sequence that stopped to ask a question both clear the runner mark on their way out — so a mark whose process is gone means one thing, and a stop that is waiting for a person is left waiting rather than relaunched into the same question. A runner that dies three times in three hours does not get a fourth: that is a fault a restart will not fix, and saying so costs less than a session an hour spent proving it.
Five endings, and each needs a different move. Getting them confused is expensive in both directions: waiting out something that will never come back, or restarting something that was one turn from finishing.
| Ending | What phasekit does | Why not the obvious thing |
|---|---|---|
| The allowance ran out | Reads the announced reset time, sleeps until it, resumes the same conversation | A fixed twenty-minute wait spends every retry before a three-hour reset arrives |
| The connection dropped | Backs off a minute or so and resumes the same conversation | Waiting out a usage-limit interval idles half an hour over a fault that is usually gone in seconds |
| The context window filled | Picks the same target up in a fresh conversation, given the continue prompt | A resume replays the transcript that overflowed, so it fails again on the first turn. Nothing is lost: the progress is in the branch, the commits and the ledger, never in the transcript |
| The pinned conversation is gone | Drops the pin and judges the branch on what is committed to it. If work was left uncommitted, a fresh session is handed it | The id cannot come back, so every retry spends a second arriving at the same sentence. And the work is on the branch either way — losing the transcript is not losing the diff |
| Anything else | Stops, shows what failed, says how to answer | An agent that stops to ask a question looks exactly like a crash from the outside, and retrying it just re-asks |
The classifier reads only text the runtime wrote — the CLI's own output and the API's error — never a tool result and, for the context verdict, never the agent's prose either. An agent that mentions being low on context is describing its situation, not ending, and throwing away a working session over that sentence is worse than the problem.
A target may be picked up in a fresh conversation twice before phasekit stops and asks for
a person. A third would be a loop spending the whole allowance re-reading the same plan,
and resizing the target is a decision, not a retry. Set it with
"usageLimit": { "maxContextRestarts": 2 }.
phasekit logs -Followfollows the sequence across phases, rolling onto each new log as it is created. Between two phases it has nothing to roll onto: the gates, the merge and the push all happen without the agent, so none of them reach a phase log. On a full gate list that is twenty minutes in which the newest log is the one that stopped growing before the gates began — and the last thing on screen is whatever the agent said half an hour ago, which is indistinguishable from a run that has died.
So the sequence keeps a journal of its own, logs/auto-progress.log, and the follower
shows it in exactly those gaps:
| 23:22:23 G.10 : resuming the agent
| 23:22:28 G.10 : pinned session gone - judging the branch instead
| 23:22:29 G.10 : merging - the gates run first
| 23:22:29 gates: 8 to run
| 23:24:56 PASS backend tests
| 23:26:29 PASS frontend tests
| 23:42:35 PASS browser suite
| 23:43:11 G.10 : merged
| 23:43:15 F.13 starting
It is truncated at the start of each sequence, because the question it answers is where the run is now, and scrolling past last week's merges to find that out is where this started. Attaching mid-run prints the last few lines first, then follows.
An agent that is really stuck is a different thing: its CLI is alive, so nothing else
notices, and the run waits for it forever. One Antigravity run once sat for six and a half
hours on "root agent idle; waiting for 2 background task(s) to finish". So while an agent
runs, phasekit watches its log: once nothing has been written for "stallMinutes" (45 by
default, long enough for a full gates run inside one tool call; 0 turns it off), it stops the
agent's processes and resumes the same conversation in a fresh process, counted as one of
the run's retries. Antigravity's idle line is given a fifth of that time.
A log is also dated by its own clock rather than by the reader's. Not every event in the
stream carries a timestamp — the one that says the phase ended carries none at all — and
filling that in from Get-Date printed a run that died at ten as one still working at
one. And a run that failed no longer renders as the same green DONE as one that worked:
FAILED, the subtype, and the error the runtime gave.
A target that ends without committing is the one stop with a mechanical answer, so
auto gives it rather than waking somebody to type the same sentence. There are two
ways to give it, and which is available decides:
| The conversation is still there | A reply into it. Far the cheaper: it already knows what it was doing |
| The conversation is gone | A fresh session, handed the work on the branch and the task it was for |
Never -c. Continuing "whatever was last spoken to in this directory" can land on a
person's own session and hand it an instruction to commit somebody else's work.
The fresh session is told to read the diff as a reviewer, not as its author, and that it may discard what is wrong-headed rather than incomplete. That half matters: the one thing known about the earlier attempt is that it did not finish, and an agent told simply to "commit what is there" will commit a half-written refactor as readily as a done one.
By hand, the same thing:
phasekit finish G.6Once per target either way. A target arriving here a second time was not asking what the answer assumed, and that stop is the honest one.
The terminal that printed the failure belongs to a detached process nobody was watching, so the stop note is the whole record. Sending the reader back to reproduce a fifteen-minute suite to find out which assertion broke is not a stop note.
That means the tail of the output is the wrong thing to keep. vitest and pytest print each
failure where it happens and the counts at the very end, so the last lines of a red run are
the names of tests that passed, followed by 1 failed | 457 passed — a number the reader
already had, for a failure nobody can name. phasekit looks through the whole output for the
lines that carry a failure, keeps a little of what follows each one, and keeps the counts as
well, marking where it cut. Anything whose vocabulary it does not recognise falls back to
the tail, which is where it was going anyway.
The same goes for a target that ended without landing. The verification can only report what
the repository shows, such as the branch has no commits on it. The reason is nearly always a
question the agent stopped to ask, and it used to sit in a JSONL log. So the note also quotes
what the agent said last: its final message, or its last prose if it was cut off
mid-turn. Tool output is never quoted, because a file the agent happened to read is not
something it said. Long messages keep their end, which is where the question is.
A sequence that stops says so. A sequence that is killed says nothing at all, because the process that would have said it is the one that died — no marker, no notification, nothing. That is the one failure an unattended run cannot report on its own, and it once cost three hours: the run was waiting out a usage limit, the terminal that launched it went away, and the wait simply never ended.
So the runner records which process it is and which target it is on, and every screen that reports on the sequence can ask that process whether it is still there:
runner process 36108, since 03/09 18:12
runner no process — the runner was killed on H.5, it did not stop
Two facts are recorded rather than one — the pid and the moment that pid started — because pids get handed out again, and a stale mark whose number now belongs to a browser would report a dead sequence as healthy. That is the exact lie the mark exists to prevent.
The mark is also how two runners see each other: starting phasekit auto while another
one is alive on the same repository is refused, since both would merge, both would push,
and the second would verify branches the first is still writing.
phasekit dashboard # one screen, then back to the prompt
phasekit dashboard -Watch # the same, redrawn every 20 seconds phasekit real-estate-search 02/09 13:53
██████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 15 / 53 28%
now G.8 coordinates on the first run running 9m
on opus / effort high context 55k
so far 70 requests, 45k new in, 3.9M cache read, 255k cache write, 38k out, ~$4.70 at API prices
next G.9 H.1 H.2
pace typical target 25m quickest quarter 19m (14 measured)
5h 52m per target as it has actually gone, waits included
left 38 targets ~16h 4m of work ~9d 6h at the observed pace
forecast ends ~Fri 05/09 10:05 if it keeps running (between Thu 04/09 and Tue 09/09)
allowance 5h 73% used, resets 01:40 week 78% used, resets Wed 03/09 12:00 (estimated, all accounts together)
accounts * main no warning from Claude (it reports a share only near the limit)
b 5h 100% (resets 19:42) week 91% (resets Fri 03:00)
since 29/08 21:59 (3d 15h elapsed)
0 ████ 4/4 A ██████ 6/6 G █████░░░░░ 5/10 H ░░░░ 0/4 B ░░░░░ 0/5
C ░░░░ 0/4 D ░░░░░░░░░ 0/9 E ░░░░░░ 0/6 F ░░░░░ 0/5
Two estimates, because there are two clocks and on a subscription they disagree by an order of magnitude. Of work is the median target projected over what is left: what the sequence costs when it is allowed to run. At the observed pace is the wall clock since the first target started, divided by the targets finished within it — allowance resets, dropped connections and sleeping laptops included.
The gap between the two is the reading. Close together, the sequence is running freely and the estimate is the work. A factor of ten apart, what stands between you and the end is the allowance, and writing a faster plan would change nothing.
The typical target is a median rather than a mean on purpose: one target that sat out a weekend waiting for a limit to reset moves a mean by a factor of nine, and an estimate built on that quotes months.
What is being used, exactly and not. The tokens are exact: every request reports them,
and so far adds up the target in hand, every attempt and review included, by kind (new
input, cache read, cache write, output). The same line follows every turn of the agent in
phasekit logs -Follow, and phasekit spend has it per target. The dollar figure is what
the same tokens would cost on the API. A subscription is not billed by them; it is there
because it is the one number that prices every kind of token and every model alike.
What is left of a subscription is not exact, and cannot be: no published figure turns tokens into a share of a five-hour or weekly allowance, and Claude states a share only near the limit (a warning) or at it (a refusal). accounts shows those statements as they are, per account, with when each window resets; "no warning" means below the warning, not 0%. allowance is phasekit's estimate in between, from those statements and the tokens spent, for every account together.
Forecast answers the question the two estimates leave open: on which day does it end? It walks the work that is left through the subscription's two windows, the five-hour one and the weekly one, the way the run will meet them:
- What a target costs. Every session's log ends with a
resultrecord carrying itstotal_cost_usd, the API-price equivalent. Each model is priced at its own rate there. The cost is spread over the session's requests in proportion to their input tokens, so it can be placed in time. The forecast uses the last twelve finished targets, because the model, the effort and the size of the work drift over a sequence. A target configured for another model is scaled by the price ratio: Sonnet 0.6, Haiku 0.2. - How much a window holds. Every
rate_limit_eventnames its window, the reset, and a utilization (a warning) or a rejection (100%). The spend inside the window up to that moment, divided by the utilization, is the window's size. The weekly size is taken from the most recent week, because allowances change. The five-hour size is the median of the last ten windows. Your own use of the account outside the sequence is not in the logs, so the size comes out small, and the date errs late rather than early. - The walk. Work runs while both windows have room. A full window stops the clock until its reset. The weekly reset keeps its fixed weekly time. The walk is done three times: with the quickest quarter of recent targets, the typical one and the slowest quarter. That gives the date and the range around it.
- Between targets. The gates, the review and the merge run outside every agent's log. Their time is the median gap between one target's last request and the next one's first. Gaps of two hours or more were waits, and they are left out.
- When the work can go elsewhere. The windows are measured from every account's logs
together, as one pool. With
limitFallbackset, a spent Claude allowance hands the target to the fallback instead of stopping it, so the walk waits for no reset, and the allowance line says so. WithswitchAccountsand another account free now, the walk starts on an empty allowance.
It assumes the machine stays on and no stop waits for a person: the observed pace above is the reading that includes those.
phasekit forecast # the date, the range and how full each window is
phasekit forecast -Json # the same as JSON, local ISO times, for another tool to readThe logs are parsed once and cached in usage-cache.json in the log directory, keyed by
each file's name, size and write time, so only the log being written is read again.
The dashboard remembers nothing else: every number is read fresh from the repository, the plan and the log directory. That is what makes it honest about a run it never saw start, one that died without saying so, and a target somebody finished by hand between sequences, none of which a progress file kept by the runner would have known about. It is also why a stop marker left behind by a run that was since answered by hand is reported as probably stale rather than as an alarm: work happening after the marker was written is the evidence that somebody dealt with it.
The dashboard answers how far and how long. phasekit steps answers the other
question somebody has while watching it — what is G.2, and why does it come after
phase D:
PHASE B the foundations 0/5
[>] B.1 generated API types + drift gate
Generate TypeScript from the FastAPI OpenAPI document
(openapi-typescript). The generated file is committed so the
frontend builds without a running backend.
note: Where the OpenAPI document is vague, fix the router's
response_model - never paper over it with a hand-written type.
It is read out of the plan itself — the phase headings, the target headings, and the
sentence each section opens with — so it cannot drift from the work the way a second
description would. phasekit steps G narrows to one phase; phasekit steps G.2 prints
that target's section in full, which is the whole point: nobody should have to open a
two-thousand-line file to find out what the target on screen is about.
Summaries are printed for what is still ahead and not for what has landed. A finished target's rationale is in the git history; on this screen it would push the part that still matters off the bottom.
phasekit.json, found by walking up from the current directory:
{
"workingDir": ".",
"codeDir": ".",
"plan": "PLAN.md",
"prompts": "PROMPTS.md",
"logDir": ".phasekit/logs",
"model": "opus",
"effort": "high",
"branchPrefix": "plan/phase-",
"requireCleanTree": true,
"autoCompact": 150000,
"usageLimit": { "maxRetries": 6, "waitMinutes": 20, "maxContextRestarts": 2 },
"gates": [
{ "name": "tests", "cwd": "backend", "run": "pytest -q" },
{ "name": "types", "cwd": "backend", "run": "pyright" },
{ "name": "build", "cwd": "frontend", "run": "npm run build" },
{ "name": "browser", "cwd": "frontend", "run": "npm run e2e", "retries": 1 }
]
}retries on a gate is opt-in and absent everywhere it is not written down. A failing test
is not worth running twice, and a gate that quietly does turns a regression into a coin
toss. It is there for the one kind of gate whose failures are not all the code's own — a
browser suite drives real servers on real ports, and a run that collided with the previous
one's teardown reports the product as broken. Unattended, that answer stops the sequence
until somebody comes back. Every retry is printed, and a gate that only passed on the
second attempt says so: it is a defect report, not a green tick.
"verify": "full" is the default: every gate runs before every merge. "verify": "fast"
lets the slowest gates wait for the end of a milestone. You mark them on the gate:
"verify": "fast",
"gates": [
{ "name": "tests", "cwd": "backend", "run": "pytest -q" },
{ "name": "browser", "cwd": "frontend", "run": "npm run e2e", "retries": 1, "slow": true }
]In fast mode a target merges on the gates not marked slow, and its prompt tells the agent
to leave the slow ones out as well, so neither the agent nor the merge spends their minutes.
Every gate, slow ones included, runs at a checkpoint:
- the last target of a milestone, where the milestone is the target's id without its last
part (
M4.3is inM4;2.1.4is in2.1), so a checkpoint falls wherever the next target's milestone differs; - the last target of the sequence;
- any
autoSequenceentry with"checkpoint": true; - any target the sequence does not list, and any target with no dot in its id.
The agent of a checkpoint is told that the slow gates have not run since the last one, and that a failure there is still its to fix. The merge prints the gates it deferred and to which target, and so does the journal.
What it costs. A regression only a slow gate catches is found at the checkpoint, not at the target that caused it. By then later targets may sit on top of it, and the agent fixing it did not write it. A slow gate failing at a checkpoint stops the sequence like any other red gate. Choose fast when the slow gates take many minutes, the targets in a milestone are small, and an occasional repair at the milestone's end is cheaper than paying those minutes on every target. Keep full when the slow gates are the ones that catch what matters most, or when a milestone is long.
Fast mode changes nothing outside the gates: the commit, the merge preconditions and
phasekit gates, which still runs the whole list, are as they were.
"strictMcp": true starts every session with --strict-mcp-config and nothing beside it,
so the agent gets no MCP server: neither the project's nor the claude.ai connectors of the
account it runs under. Off by default. Turn it on when the agents only write code: a mail
account or a document store has no business in a run nobody is watching, and every tool
the session is handed is carried by every request it makes.
Two things a new target is told before it starts, both on by default:
-
"skipVerifiedGates": when the gates last passed on exactly the tree the target starts from, with the same gate list and a clean working tree, the prompt says so. The agent then skips the gate run its CHECK FIRST step would make. That run used to cost minutes and tokens to re-measure what the merge had just measured. Any change, committed or not, brings the run back, and the gates before the commit and before the merge are unchanged. The measurement is recorded ingates-green.jsonin the log directory. -
"handoff": the prompt carries the previous target's final report: its commit, its gate results, what it decided and what it noticed. It is capped at 3000 characters. The session starts by knowing what just landed instead of exploring the code to find out.Why not continue the previous conversation instead? Because a request costs what its context costs. A fresh session starts at a few tens of thousands of tokens. A continued one starts where the previous target ended, often above a hundred thousand, and every request of the new target would carry that.
Set either to false to turn it off.
Every target is a fresh conversation, so whatever an agent learned the hard way died with it: a flaky test and its exact signature, a tool that behaves unexpectedly, a command that outlasts the shell. On one measured project the same flaky browser test was rediscovered, investigated and dismissed in four separate targets.
With "lessons" on (the default), every prompt carries a short list of lessons earlier
agents verified, and every agent ends its final message with a block that updates it:
LESSONS
ADD: when <condition> | <what happens, and what to do about it> | evidence: <test, command, log line>
CONFIRM L3: <how it saved work in this target>
WRONG L5: <the evidence that it is wrong or out of date>
EDIT L2: when <condition> | <the corrected lesson> | evidence: <...>
or the single line NONE. phasekit, not the agent, applies it, one operation at a time:
- Scored. A lesson starts at 2. Another target that confirms it adds 1, once per target;
the target that added it cannot vouch for it.
WRONGtakes 2, so one contradiction with evidence retires a new lesson, and one several targets confirmed survives a single doubt. At 0 a lesson is retired. The same lesson added again by another target counts as a confirmation, not a copy. - Bounded. At most
"lessonsMax"lessons (30) are kept, the weakest retired first, and the prompt carries at most"lessonsMaxChars"(6000) characters of them, best first: every line is read by every request of every target. - Evidence and condition required. An
ADDwithout its three parts, or longer than 200 / 400 / 300 characters, is refused and the refusal is printed. The condition stays: a lesson without its "when" becomes a wrong rule. - Kept outside the branches. The store is
lessons.jsonin the log directory. It is collected after every agent run whatever the outcome, so a target that failed, stopped or was thrown away still leaves what it found. Retired lessons are kept with the reason. - A hint, never a verdict. The prompt says that a lesson never replaces running a gate or reproducing a failure. The gates decide; phasekit runs them itself before every merge in any case.
- Never in the way. A store that cannot be read is reported and left untouched, never overwritten. Collecting a lesson can fail; it cannot fail a run. Writers take a lock, and a file is replaced whole, so a reader never sees half of one. Stop notes and the handoff leave the block out, so it never pushes the agent's question out of view.
Why this shape: a model asked to rewrite a growing list summarises it into something
shorter and vaguer, so the list is only ever edited item by item
(Agentic Context Engineering). Scores that later
agents raise and lower let the list clean itself
(ExpeL). And agents do write confident, wrong
conclusions and then act on them
(memory confabulation), which is why evidence is
required, one WRONG retires a new lesson, and the gates stay the judge.
phasekit lessons lists them. An answer you give to a stop is often a lesson too; record
it with phasekit lessons add. "lessons": false turns the whole thing off.
Two choices, both off by default, because each costs sessions.
"review": true puts an independent reviewer between a finished target and its merge.
It is a separate session that did not do the work and cannot change anything: it gets file
reads and the git commands that only read (diff, log, show, status, blame), and
no editing tool, by construction rather than by request. Its only job is to show the work
is wrong: a requirement not met, behaviour that contradicts the plan, tests that do not
test what they claim or were weakened, a regression, a report that claims more than the
commit holds. It must point at a file and line, and it is told that an invented finding
costs a round. It ends with VERDICT: PASS or VERDICT: FAIL.
"review": true,
"reviewModel": "opus",
"reviewEffort": "high",
"autoSequence": [ "4.1", { "target": "4.2", "review": false } ]An entry's own "review" wins over the global one, either way. The gates still run after
a PASS; the review adds to them and never replaces them. A review that ends with no verdict
is said in the journal and the gates decide alone. A reviewer that changed the repository
(it cannot, but it is checked) stops the sequence: its verdict is then worth nothing.
phasekit review <target> runs it by hand on a branch as it stands.
"fixRounds" decides what happens when a target is rejected, by the gates before its
merge or by the reviewer. Empty, the default, means what it always meant: the sequence stops
and waits for a person. Each entry is one more round in the target's own conversation,
told exactly what was rejected and why:
"fixRounds": ["same", "opus/xhigh"]"same" keeps the target's model and effort; "opus/xhigh" (or just "opus") moves up
for that round. So a target written by Sonnet that fails its gates gets one more try on
Sonnet, then one on Opus at extra-high effort, and only then wakes anybody. After a review
rejection the next review sees the findings and the builder's answer, and accepts an answer
backed by evidence; the builder is told it may refute a finding rather than "fix" code that
was right. Every round is told never to weaken a test or a gate. When the rounds run out,
the stop note says how many there were.
Rounds do not apply to a target that ended without finishing (a question, uncommitted work): those are the stops the arbiter is for.
Most stops are a question, and most questions have a technical answer: which of two readings of the plan the plan supports, how to measure something, what to do when two requirements collide over an internal number. On a real 47-task build every question after the first week was one of those, and the time lost was the hours each one waited for somebody to read it.
"arbiter": true puts those questions to an independent model before anybody is woken.
It is read-only like the reviewer (file reads, the git commands that only read, nothing that
edits, and a repository that changed while it ran voids its decision). It reads the question,
the task, the plan and the code, and ends with one of two answers:
DECISION: ANSWER, only when the answer is technical, changes nothing a user of the product would see, do or be asked, lowers no bar (no test, gate, security or data-safety rule weakened to get the task through) and the plan gives it enough to be sure. The answer goes to the agent in its own conversation and the target carries on, through the reviewer and the gates as usual. A plan amendment is allowed under the same conditions, and the agent is told to make it in the plan and the decision log, in the same commit.DECISION: ESCALATEfor everything else, and whenever it is unsure. The sequence stops as it always did, and the stop note carries the arbiter's summary: the question, the options, its recommendation.
"arbiter": true,
"arbiterModel": "opus",
"arbiterEffort": "high"Once per target: a question that comes back after the answer reaches a person. Every answer
is written to logs/decisions.md, the question and the answer side by side, for the owner to
read. One you disagree with is undone with a fix task; a kind of question you want to keep
answering yourself means turning the arbiter off. It also answers a fix round that stops to
ask, which is where requirements tend to collide. Off by default.
Any model can also be one of Google Antigravity's, run through its CLI (agy) under the
Antigravity account's own plan quota, separate from Claude's. Write it as agy: and the
model's identifier, as agy models lists them:
"model": "opus",
"reviewModel": "agy:gemini-4-hydrogen-high",
"fixRounds": ["same", "agy:claude-opus-5-5-high"],
"autoSequence": [ "1.1", { "target": "1.2", "model": "agy:gemini-3.8-flash-medium" } ]That reads: tasks on Claude Opus through Claude Code; the reviewer is Gemini, a different
family from the builder, which is what an adversarial review wants; a rejected task gets
one more round on its own model, then one on Opus through Antigravity's quota; task 1.2,
mechanical, runs on Gemini Flash. The identifiers carry their effort (-low, -medium,
-high, -xhigh), so effort does not apply to them. Antigravity offers Gemini
(Argon, Hydrogen, Flash, Orchestrator), Claude and GPT-OSS models, depending on the plan;
its quotas are two pools, Gemini models and "Claude and GPT models", each with a weekly
and a five-hour limit.
Setup, once: install the CLI (irm https://antigravity.google/cli/install.ps1 | iex on
Windows; other systems), run
agy once to sign in, and agy models to see your identifiers. phasekit lint refuses a
plan that names an agy: model when the CLI is not installed.
What phasekit does, measured against agy 1.5.9:
- The same loop. A target on Antigravity is run, resumed (
--conversation), verified, reviewed and merged like any other; its log reads the same inphasekit logs, its last words reach stop notes and the handoff, its LESSONS block is collected. - No paid credits by surprise. Every session is started with
useG1Creditsoff, so a spent plan quota waits for its refresh instead of drawing on purchased AI credits."agyCredits": trueallows them. - A read-only reviewer that really is. A headless agy run with no approvals still
writes files (measured), so the Antigravity reviewer runs in plan mode, which changes
nothing in the project, with only
git diff/log/show/status/blameallowed and the diff handed to it in the prompt. phasekit still checks the tree afterwards. - Changing CLI between rounds. A conversation cannot move between Claude Code and Antigravity, so a fix round on the other CLI starts a fresh session over the branch, told what was rejected.
- A spent quota is a wait. When agy reports one (
RESOURCE_EXHAUSTED, "quota"), the run waits and resumes the same conversation. agy announces no reset time, so the wait iswaitMinutes, repeated up tomaxRetries; for a weekly limit raise those, or let the sequence stop.
phasekit spend counts Antigravity's usage too (each response's own token count). The
forecast's allowance model and phasekit account are Claude's only.
With Claude and Antigravity both available there are a dozen models to choose from. You
can choose for each task yourself ("model" on its entry), or let phasekit choose from
the plan, using a model per tier that you set once:
"autoTier": true,
"tiers": {
"mechanical": "agy:gemini-3.8-flash-medium",
"standard": "opus/medium",
"hard": "opus/xhigh"
},
"review": true,
"reviewModel": ["agy:gemini-4-hydrogen-high"],
"fixRounds": ["same", "opus/xhigh"],
"limitFallback": ["agy:claude-opus-5-5-high", "agy:gemini-4-argon-high"]- Tiers. A task is mechanical, standard or hard. An entry can name its tier
(
{ "target": "4.2", "tier": "hard" }); with"autoTier": truephasekit reads it from the task's plan section: two or more signs of a hard problem (a race, an invariant, a migration, security, performance, data loss...) or more than 900 words make it hard; signs of mechanical work (docs, README, screenshots, renames, version bumps) with no hard sign and under 500 words make it mechanical; the rest is standard. Deliberately plain, so it can explain itself:phasekit modelsprints every target's model and effort and why. An entry's own"model"always wins, and its"effort"applies on top. Without"tiers", mechanical is sonnet/medium, standard the configured model, hard the configured model at xhigh. Routing up front and escalating on failure (fixRounds) is the combination the routing literature finds best. - Several reviewers.
"reviewModel"takes a list. Each reviews on its own; one rejection sends the work back, with every rejecting reviewer's findings, named. A reviewer of another family than the builder is the cheapest gain: judges tend to favour output like their own, and different families share fewer blind spots, though not none. - A second quota instead of a wait.
"limitFallback": when the target's model runs out of allowance in the middle of the task,phasekit autohands it, in a fresh session over the branch, to the next model in the list instead of waiting for the reset. Antigravity carries Claude models too, under its own quota, so"agy:claude-opus-5-5-high"continues with the same family. When the list runs out, the last one waits, as before. With"switchAccounts": trueand more than one Claude account on the machine, the other accounts come first: the same conversation carries on under one that is not spent, and the fallback is used only once every account is (details).
What phasekit tells each family, from their own vendors' guidance and the measured differences between them:
- Project instructions reach both. Claude Code loads
CLAUDE.md; Antigravity loadsAGENTS.mdandGEMINI.md, notCLAUDE.md. The prompt names the files the CLI running it will not load, so a project written for one is not invisible to the other. - Gemini gets a short working discipline: stay in scope, look up an API's real signature before calling it, fix the cause, claim a check only after running it. Those are the failure modes reported for Gemini agents (scope creep, guessed signatures, surface fixes), and Google's guidance is concise, direct instructions. Its thinking level is part of the model id: medium is Google's default for agentic coding, high for the hardest tasks, and higher levels also make it call more tools.
- Claude is told that its context is compacted automatically, so it does not cut work short to save it, which is Anthropic's guidance for harnesses that compact.
Where each tends to fit, as the published comparisons stand in November 2026: Claude Opus
leads on terminal-based agentic coding and on full coding-agent benchmarks; Gemini models
are close on code, cheaper, with very long context. So: Claude for the hard tasks, Gemini
Flash for mechanical ones, a Gemini reviewer for Claude's work, and the other quota as the
fallback. Measure on your own plan: phasekit spend shows what each target cost and the
stop notes show what failed.
workingDir is where the agent is launched; codeDir is the git repository that receives
the branch and the commits. They differ when the plan lives in a separate notes repo — set
workingDir to their common parent so the agent can see both.
Every relative path is resolved against the config file, never against the shell's current directory, so the same command means the same thing wherever you type it.
Wall clock is what the dashboard answers. On a subscription it is the wrong question: two targets that each took an afternoon can differ tenfold in what they spent.
The reason is that a request costs what its context carries, and a session's context only grows. Measured over one real cycle, a typical target ran 60–120 requests and peaked around 250k tokens of context. One target ran 374 requests and climbed to 542k, spending its last 174 requests above 460k — and cost eight times the typical one. Nothing in that tail was harder than the work at the start. It was the same work, carrying every earlier turn again.
$ phasekit spend
target attempts requests peak ctx weighted
H.5 1 95 293k 2.5M
B.1 1 162 313k 4.1M
B.2 1 374 543k 16.4M
weighted is one number in units of a full-price input token — a cached read counts a
tenth, writing the cache a quarter more, output five. Only the ratios are real; the
number exists to put two targets next to each other honestly.
Two things keep that curve flat, and both are on by default:
autoCompact(default150000) is passed to every session, resumes included, and caps the conversation instead of leaving the ceiling to the CLI. The context then sawtooths under the ceiling rather than climbing past half a million.{{SECTION}}in a prompt block is replaced with that target's own section of the plan. A prompt that says "read PLAN.md" costs about 16k tokens on a real plan — and unlike a one-off cost it is then re-read by every request the session goes on to make. Quote the section; leave the file for the rare task that needs its neighbours.
A target that peaks far above the ceiling either ran before it existed or is a task that was planned too large. The second is a planning finding, not a runner bug: 374 requests is not one unit of work.
One commit per task. A phase you dislike is one git branch -D away. A task you
dislike is one git revert away. Without this the only available verdict on an hour of
agent work is "keep all of it" or "throw all of it away".
Every phase verifies the previous one. Not by reading the ledger — by running the
gates and grepping for the consequences. A ticked box with no commit behind it is the
single most expensive failure in this workflow, because every later phase compounds it.
phasekit status prints the ledger next to the git log for exactly this reason.
Waiting is not failing. When the subscription allowance runs out, claude -p exits
with an error — it does not wait and resume by itself. phasekit reads the reset time out
of the message and sleeps until it, then resumes the same conversation, so the agent
carries on from the task it was on rather than restarting the phase. A run in that wait
has no claude process and a log that stopped growing; it is alive, and it is the single
most common thing to mistake for a crash.
A transcript is not where the progress is. The branch, the commits and the ledger are, which is why a conversation that outgrows its context window can simply be abandoned and the same target picked up in a fresh one. Every other design here follows from that: one commit per task, a ledger checked against the git log, and gates that re-establish the truth from the repository rather than from anybody's memory of it.
What one agent learns, the next one knows. A trap one target paid for is written down with its evidence and handed to every later target, scored by the ones it helped and retired by the one it misled. A lesson is a hint; the gates are the verdict.
Stopping is a success. An agent that stops to say "this task's premise is false" has done the most valuable thing it can do. The runner shows the log tail when a run ends non-zero, because a stop-to-ask and a crash look identical from the outside, and answering costs one turn while restarting the phase costs the whole baseline.
Most of phasekit came from running it and fixing what broke. These are the published sources that reached the same conclusions, or that shaped a later change, so that "why is it done like this?" has an answer you can check.
- A fresh session per unit of work, oriented by notes and git, verified at the start. Anthropic, Effective harnesses for long-running agents (2025): each session reads a progress file and the git log, checks the app still works, does one feature, tests it and ends with a commit. Here: one target per conversation, the handoff, CHECK FIRST, one commit per task.
- Compaction, structured notes kept outside the context window. Anthropic,
Effective context engineering for AI agents
(2025). Here:
autoCompact, the handoff, the lessons store. - Instructions are context, not enforcement. Claude Code documentation, How Claude remembers your project: to guarantee something happens, do not rely on a line in a prompt. Here: the gates are run by phasekit itself before every merge, whatever the agent reported.
- Edit a growing list item by item, never rewrite it whole. Zhang et al., Agentic Context Engineering (2025), on "context collapse". Here: the LESSONS operations.
- Let later experience raise and lower what was learned. Zhao et al., ExpeL: LLM Agents Are Experiential Learners (AAAI 2024), with its ADD / EDIT / UPVOTE / DOWNVOTE insight list. Here: lesson scores.
- Agents write confident, wrong conclusions and then act on them. Honest Lying: memory confabulation in reflexive agents (2026), and the survey Memory for Autonomous LLM Agents (2026), which proposes requiring evidence for every reflection. Here: evidence is mandatory, a target cannot confirm its own lesson, one contradiction retires a new one, and a lesson never overrides a gate.
- Fresh context every iteration beats one long conversation. Geoffrey Huntley's
Ralph loop, the simplest form of the idea:
while :; do cat PROMPT.md | claude; done. phasekit is the same loop with a plan, branches, gates, limit handling and a verdict on every iteration. - Route by difficulty, escalate on failure. Moslem & Kelleher, Dynamic model routing and cascading for efficient LLM inference (2026): cascade routing beats routing or cascading alone, and quality estimation is the key factor. Here: tiers (routing) plus fixRounds (escalation), and a classifier that says why it chose. Agent-level results: AgentRouter (2026).
- A reviewer of another family. Judges favour outputs like their own (Wataoka et al., arXiv 2604.22891); a verifier from a different family catches inconsistencies the same model misses (arXiv 2604.21282); but different providers still fail together more than chance (arXiv 2609.03422), and most shared failures trace back to the specification (N-version programming with coding agents). Here: reviewModel takes several, of any family, and the plan stays the first defence.
- What each CLI loads, and how to prompt each family. Antigravity's rules and CLI best practices (AGENTS.md / GEMINI.md, verification, plan then execute); Google's Gemini 3 developer guide and what's new in Gemini 3.5 (concise prompts, thinking levels, more tool calls at higher levels); Anthropic's prompting best practices (state in git and structured files, verification tools, say when context is compacted). Measured behaviour of Gemini and Claude agents: DataCamp and index.dev comparisons; benchmarks of Gemini 4 Argon vs Claude Opus 5.5 and Gemini 4 Carbon vs Claude Opus 5.5, whose small gaps come from different harnesses and deserve caution.
Others solve the same problem differently, and two of phasekit's options come from them.
- claude-autopilot: plan once, then one
verified commit per task overnight in a worktree. Its optional reviewer session per task
and its escalation of a failing task to a stronger model are where
"review"and"fixRounds"come from, and its planning session, which asks each question with a recommended answer, is the model forphasekit draft. - harnessd: builder and evaluator negotiate a contract per work packet before any code, and a read-only adversarial evaluator tries to disprove the builder's claims, which is the stance phasekit's reviewer takes.
- continuous-claude: a loop that opens a pull request per iteration, waits for CI and merges.
- GitHub Spec Kit: turns a specification into a plan and a task list for any coding agent. A good way to write the plan phasekit then runs.
- docs/method.md — why the plan is shaped this way
- docs/writing-a-plan.md — how to write tasks an agent can execute
- docs/troubleshooting.md — the failure modes, and what they look like
Apache License 2.0. Versions published before 15 November 2026 were released under the MIT licence and remain available under it.
