Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Claude Code mods (plugins with a hooks module), served as a local folder marketp
| mod | version | what it does |
| --- | --- | --- |
| [harness](harness/) | 0.3.4 | The integrated harness: the user's Claude rules enforced at the tool call, session tooling and workflow automation (formerly house-rules) |
| [auto-claude](auto-claude/) | 1.0.0 | Unattended run of a repository through to live: plans the long-term goal, milestones and deploy; its own loop builds and judges each milestone in a worktree; ships each (push, PR, required CI, merge), deploys and smoke-checks it; a watchdog repairs or routes around stalls; replans until the final check passes. Absorbed goal-mode in 1.0.0 |
| [auto-claude](auto-claude/) | 1.1.0 | Unattended run of a repository through to live: plans the long-term goal, milestones and deploy; its own loop builds and judges each milestone in a worktree; ships each (push, PR, required CI, merge), deploys and smoke-checks it; a watchdog repairs or routes around stalls; replans until the final check passes. Absorbed goal-mode in 1.0.0; since 1.1.0 the session never rests: the next milestone is built, stacked, while a PR waits on CI |
| [model-tier](model-tier/) | 0.11.0 | Routes each main-loop turn to fable, opus, sonnet or haiku and a reasoning effort by task complexity, with a `set_tier` tool the model calls to correct either |
| [refactor](refactor/) | 0.1.3 | Enforces the architecture a repo declares in `.claude/architecture.json` at Edit/Write (layer direction, forbidden imports), notes code smells with the refactoring.guru technique to apply, `/arch audit` for violations and import cycles |

Expand Down
2 changes: 1 addition & 1 deletion auto-claude/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "auto-claude",
"version": "1.0.0",
"version": "1.1.0",
"description": "Finishes a repository's work unattended and live: Claude plans the long-term end state, its milestones and how it deploys; the built-in loop builds each milestone in its own worktree and judges it; auto-claude ships it (push, PR, CI, merge when green), deploys and smoke-checks it, and a watchdog keeps the run moving until the final check passes. Absorbs goal-mode's loop (1.0.0).",
"author": {
"name": "unohee"
Expand Down
7 changes: 5 additions & 2 deletions auto-claude/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ goal-mode merged into auto-claude in 1.0.0 (see "From goal-mode" below). Its loo
- Right before landing, the milestone's check runs once more in a **fresh checkout**: a detached worktree at `worktrees/auto-verify`, made from the branch head fetched from origin (github) or from the rebased commit (local). A check that passes only in the builder's worktree becomes a fix goal, like a red CI.
- When CI fails or the PR conflicts, auto-claude appends a fix goal built on the milestone's branch (`:: base: goal/NN-…`), and the loop builds that next. After 3 failures the milestone is held.
- **Deploy.** After each merge, as the plan says (see "Deploying").
- **The session never rests through CI.** While a PR waits on CI, the next milestone starts at once, **stacked** on that PR's branch: the commit it starts from is recorded. Up to 2 milestones are built ahead this way. They ship in order. When the one before lands (squashed) or is held, the stacked branch runs `git rebase --onto origin/<default> <recorded commit>`, which drops its parent's commits, and is then pushed like any other. A rebased branch is pushed with `--force-with-lease`, since the session may have pushed it before. A stacked branch that does not rebase cleanly gets a fix goal that does the rebase by hand. While a broken deploy is being repaired, nothing new is stacked and nothing stacked ships: the repair, built from the default branch, lands and deploys first. A fix goal (`:: base:`) always starts on its own base.
4. **Finish or replan.** When the queue is done, auto-claude runs the final check on a fresh checkout of the merged default branch.
- If it passes, auto-claude deploys once more if a deploy is still due. Then it writes a `## Result` section and stops.
- If it fails, Claude appends new milestones from the check's output (round 2, and so on, up to `maxRounds`).
Expand Down Expand Up @@ -103,8 +104,10 @@ A run never asks the person to look at `status` or to run a command. When someth

| what stops | what happens |
| --- | --- |
| A milestone is open, but the session has had no turn for 3 min: the model ended its turn to "wait", a prompt was dropped, an interrupt, or a stop the judge could not read | The milestone's prompt is sent again, after 3, 6 and 12 min of quiet. After the third, the milestone is blocked and the next one starts. A stop being judged, or a retry pause, is not quiet. Turns are tracked with `turn.start` / `turn.complete`. |
| Planning ends without `auto_plan_ready` | A reminder 2 min after that turn ended, listing what the plan files lack (15 min at most otherwise). After 3, the run stops. |
| A milestone is open, but the session has had no turn for 1 min: the model ended its turn to "wait", a prompt was dropped, an interrupt, or a stop the judge could not read | The milestone's prompt is sent again, after 1, 3 and 6 min of quiet. At 12 min, the milestone is blocked and the next one starts. A stop being judged, or a retry pause, is not quiet. Turns are tracked with `turn.start` / `turn.complete`. |
| The model waits inside a turn | Refused while a run is on: `sleep` of 60 s or more (or a computed duration), `gh run watch`, `gh pr checks --watch`, `Monitor`, `CronCreate` and `ScheduleWakeup`. auto-claude watches CI, merges and deploys itself, and prompts the session when there is work. Shorter sleeps (a check waiting for a server) pass. |
| A shipping error to diagnose while the session builds another milestone | The diagnosis prompt waits until that milestone is done, so the stop judge never judges the wrong work. Nothing is held before the model was asked and had 10 min to act (after an hour unasked, the hold goes ahead). |
| Planning ends without `auto_plan_ready` | A reminder 1 min after that turn ended, listing what the plan files lack (15 min at most otherwise). After 3, the run stops. |
| An SSH remote refuses the push (`Permission denied (publickey)`) | The push goes to the https URL of the same repository. |
| The same shipping error, check after check | At 5 checks, the session model gets the error and what was tried, and fixes what it can (gh auth, remotes, `gh repo set-default`). At 10, the milestone is held and the run goes on. |
| A PR closed under the run | It is opened again once, then held. |
Expand Down
148 changes: 125 additions & 23 deletions auto-claude/hooks/auto.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,9 @@ function world(on: On, store: Record<string, unknown> = {}) {
deployExit: 0,
smokeExit: 0,
missing: new Set<string>(),
// Every `git rebase`, and whether a stacked branch's rebase --onto conflicts.
rebases: [] as string[],
rebaseFails: false,
clock: mock.clock(on, { now: 1_000 }),
}
const removed = (path: string) => [...w.gone].some(g => path === g || path.startsWith(`${g}/`))
Expand Down Expand Up @@ -172,7 +175,9 @@ function world(on: On, store: Record<string, unknown> = {}) {
if (a.startsWith('gh run list')) return ok(w.runList)
if (e.argv[0] === 'test' && e.argv[1] === '-d') return ok('', w.gone.has(String(e.argv[2])) ? 1 : 0)
if (e.argv[0] === 'test' && e.argv[1] === '-e') return ok('', w.missing.has(String(e.argv[2])) ? 1 : 0)
if (a.includes('rev-parse --verify')) return ok('', w.branchGone ? 1 : 0)
if (a.includes('rev-parse --verify')) return w.branchGone ? ok('', 1) : ok(`tip-of-${String(e.argv.at(-1)).replace(/\^\{commit\}$/, '')}\n`)
if (a.includes(' rebase ')) w.rebases.push(a)
if (a.includes(' rebase --onto') && w.rebaseFails) return ok('', 1, 'CONFLICT (content): Merge conflict in calc.py')
if (a.includes('worktree add') && !a.includes('--detach')) {
w.adds.push(a)
w.gone.delete(String(e.argv[5]))
Expand Down Expand Up @@ -439,7 +444,7 @@ describe('a run, local CI', () => {
expect((await cmd($, 'status')).text).toContain('no plan was accepted after 3 reminders')
})

test('a planning turn that ends without a plan is reminded 2 min later, not 15 (P4)', async ($, on) => {
test('a planning turn that ends without a plan is reminded 1 min later, not 15 (P4)', async ($, on) => {
const w = world(on)
await $.session.start({ cwd: '/repo', surface: 'terminal', isInteractive: true })
await cmd($, 'start')
Expand Down Expand Up @@ -571,6 +576,99 @@ describe('a run, github CI', () => {
expect(w.merged).toHaveLength(2)
})

test('the session keeps building while a PR waits on CI: the next milestone is stacked on its branch, then rebased off it and shipped once it lands', { timeoutMs: 30_000 }, async ($, on) => {
const w = world(on)
w.github = true
w.checks = '[{"bucket":"pending"}]'
await planned($, w)
await meet($, w)
expect(w.merged).toHaveLength(0)
// Milestone 2 started at once, on milestone 1's branch, with the commit it builds on kept.
expect(w.adds.at(-1)).toBe(`git -C /repo worktree add ${WT2} -b ${BR2} ${BR1}`)
expect(w.prompts.at(-1)).toContain('Milestone #2')
// Met while milestone 1 still waits: it waits its turn, unpushed.
await meet($, w)
await w.clock.advance(TICK)
expect(w.pushes.some(p => p.includes(BR2))).toBe(false)
expect((await cmd($, 'status')).text).toContain('- stacked: sub() returns a-b')
// Milestone 1 lands; milestone 2 drops its commits, then is pushed and landed the same way.
w.checks = '[{"bucket":"pass"}]'
await w.clock.advance(10_000)
expect(w.merged).toHaveLength(2)
expect(w.rebases).toContain(`git -C ${WT2} rebase --onto origin/main tip-of-${BR1}`)
// Rebased after the session may have pushed it: pushed with a lease.
expect(w.pushes.find(p => p.includes(`${BR2}:${BR2}`))).toContain('--force-with-lease')
for (let i = 0; i < 3; i++) await w.clock.advance(TICK)
expect(w.notifies.at(-1)).toContain('finished: the final check passed after 1 round(s). 2 merged, 0 held')
})

test('a stacked milestone that does not rebase once its parent lands gets a fix goal that rebases it by hand', { timeoutMs: 30_000 }, async ($, on) => {
const w = world(on)
w.github = true
w.checks = '[{"bucket":"pending"}]'
await planned($, w)
await meet($, w)
await meet($, w)
w.rebaseFails = true
w.checks = '[{"bucket":"pass"}]'
await w.clock.advance(TICK)
expect(w.merged).toHaveLength(1)
expect(w.runs).toContain(`git -C ${WT2} rebase --abort`)
const fix = parseQueue(w.files.get(GOALS) ?? '').find(i => i.base !== undefined)
expect(fix?.base).toBe(BR2)
expect(fix?.condition).toContain(`git rebase --onto origin/main tip-of-${BR1}`)
// The fix goal is built next, on milestone 2's branch.
expect(w.adds.at(-1)).toContain(`-b goal/03-`)
expect(w.adds.at(-1)).toMatch(new RegExp(`${BR2}$`))
})

test('a broken deploy is repaired before a stacked milestone merges on top of it', { timeoutMs: 30_000 }, async ($, on) => {
const w = world(on)
w.github = true
w.checks = '[{"bucket":"pending"}]'
await planned($, w, PLAN_DEPLOY)
await meet($, w)
// Milestone 2 is built and stacked while milestone 1 waits on CI.
await meet($, w)
w.deployExit = 1
w.checks = '[{"bucket":"pass"}]'
await w.clock.advance(10_000)
// Milestone 1 landed, its deploy failed: milestone 2 stays stacked, the repair is built from main.
expect(w.merged).toHaveLength(1)
expect(deployRuns(w).filter(r => r.includes('deploy.sh'))).toHaveLength(1)
expect((await cmd($, 'status')).text).toContain('- stacked: sub() returns a-b')
expect(w.adds.at(-1)).toMatch(/origin\/main$/)
expect(w.prompts.at(-1)).toMatch(/deploy/i)
// The repair lands first and deploys; only then does milestone 2 go.
w.deployExit = 0
await meet($, w)
expect(w.merged).toHaveLength(3)
const order = w.pushes.filter(p => p.includes(' push -u ')).map(p => p.split(' ').find(t => t.includes(':goal/'))?.split(':')[1])
expect(order.indexOf(BR2)).toBeGreaterThan(order.findIndex(b => b?.startsWith('goal/03-')))
expect((await cmd($, 'status')).text).toContain('3 merged, 0 held')
})

test('a shipping error is not held before the model was asked: the question waits while it builds another milestone', { timeoutMs: 30_000 }, async ($, on) => {
const w = world(on)
w.github = true
w.gitGone = true
await planned($, w)
await meet($, w)
// Milestone 2 is built for 20 min while milestone 1's push keeps failing.
await turnStart($)
for (let i = 0; i < 40; i++) await w.clock.advance(TICK)
expect(w.notifies.some(n => n.includes('held: add() returns a+b'))).toBe(false)
expect(w.prompts.filter(p => p.includes('[auto-claude] Shipping is stuck'))).toHaveLength(0)
await meet($, w)
await w.clock.advance(TICK)
expect(w.prompts.filter(p => p.includes('[auto-claude] Shipping is stuck'))).toHaveLength(1)
// It gets 10 min to act before the hold.
for (let i = 0; i < 16; i++) await w.clock.advance(TICK)
expect(w.notifies.some(n => n.includes('held: add() returns a+b'))).toBe(false)
for (let i = 0; i < 6; i++) await w.clock.advance(TICK)
expect(w.notifies.some(n => n.includes('held: add() returns a+b'))).toBe(true)
})

test('only required checks decide: a red check that is not required does not block the merge (P1)', async ($, on) => {
const w = world(on)
w.github = true
Expand Down Expand Up @@ -646,17 +744,17 @@ describe('a run, github CI', () => {
})

describe('the watchdog (P2, P4, P5)', () => {
test('a milestone whose session sits idle is prompted again at 3, 6 and 12 min, then blocked, and the run goes on', { timeoutMs: 30_000 }, async ($, on) => {
test('a milestone whose session sits idle is prompted again at 1, 3 and 6 min, then blocked, and the run goes on', { timeoutMs: 30_000 }, async ($, on) => {
const w = world(on)
await planned($, w)
const wakes = () => w.prompts.filter(p => p.includes('the session sat idle') && p.includes('Milestone #1'))
// The model ended its turn without a stop the loop could judge.
await turnStart($)
await turnEnd($)
await w.clock.advance(2 * MIN)
await w.clock.advance(TICK)
expect(wakes()).toHaveLength(0)
// Ticks are 30 s apart: the first one past 3 min of quiet wakes it.
await w.clock.advance(MIN + TICK + 1_200)
// Ticks are 30 s apart: the first one past 1 min of quiet wakes it.
await w.clock.advance(2 * TICK)
expect(wakes()).toHaveLength(1)
expect(wakes()[0]).toContain('Milestone #1: add() returns a+b')
expect(wakes()[0]).toContain('wake 1/3')
Expand Down Expand Up @@ -726,20 +824,25 @@ describe('the watchdog (P2, P4, P5)', () => {
w.gitGone = true
await planned($, w)
await meet($, w)
// Milestone 2 is built meanwhile, stacked on milestone 1's branch.
expect(w.adds.at(-1)).toBe(`git -C /repo worktree add ${WT2} -b ${BR2} ${BR1}`)
const asked = () => w.prompts.filter(p => p.includes('[auto-claude] Shipping is stuck'))
for (let i = 0; i < 5; i++) await w.clock.advance(TICK)
const asked = w.prompts.filter(p => p.includes('[auto-claude] Shipping is stuck'))
expect(asked).toHaveLength(1)
expect(asked[0]).toContain('ENOENT')
expect(asked[0]).toContain('Do not merge or deploy')
// The session is building milestone 2: the diagnosis waits for it.
expect(asked()).toHaveLength(0)
await turnStart($)
await meet($, w)
await w.clock.advance(TICK)
expect(asked()).toHaveLength(1)
expect(asked()[0]).toContain('ENOENT')
expect(asked()[0]).toContain('Do not merge or deploy')
// Ten checks are not enough on their own: the error must also have lasted 15 min.
for (let i = 0; i < 6; i++) await w.clock.advance(TICK)
for (let i = 0; i < 4; i++) await w.clock.advance(TICK)
expect(w.notifies.some(n => n.includes('held: add() returns a+b'))).toBe(false)
for (let i = 0; i < 20; i++) await w.clock.advance(TICK)
for (let i = 0; i < 26; i++) await w.clock.advance(TICK)
expect(w.notifies.some(n => n.startsWith('auto-claude (repo): held: add() returns a+b') && n.includes('going on'))).toBe(true)
// The run went on to milestone 2, which hits the same wall: the run stops instead of holding every milestone.
expect(w.adds.at(-1)).toContain(WT2)
await turnStart($)
await meet($, w)
// Milestone 2 goes next, rebased off milestone 1's commits, and hits the same wall: the run stops instead of holding every milestone.
expect(w.rebases).toContain(`git -C ${WT2} rebase --onto origin/main tip-of-${BR1}`)
for (let i = 0; i < 32; i++) await w.clock.advance(TICK)
expect(w.notifies.at(-1)).toContain('stopped: 2 milestones in a row were held for one cause (push)')
expect((await cmd($, 'status')).text).toContain('phase stopped')
Expand All @@ -765,15 +868,14 @@ describe('the watchdog (P2, P4, P5)', () => {
expect(w.adds.at(-1)).toContain(WT2)
})

test('an idle run is told to the person with what is being done, never asked to check status', { timeoutMs: 30_000 }, async ($, on) => {
test('an idle session never rests long and is never asked to check status: woken, then its milestone blocked', { timeoutMs: 30_000 }, async ($, on) => {
const w = world(on)
await planned($, w)
// The session does nothing with its milestone: woken at 3 and 6 min, told at 18.
for (let i = 0; i < 40; i++) await w.clock.advance(TICK)
const idle = w.notifies.filter(n => n.includes('idle '))
expect(idle).toHaveLength(1)
expect(idle[0]).toContain('the session has done nothing for')
expect(idle[0]).toContain('goes on by itself')
// The session does nothing with its milestone: woken at 1, 3 and 6 min, blocked at 12, the next one started.
for (let i = 0; i < 26; i++) await w.clock.advance(TICK)
expect(w.prompts.filter(p => p.includes('the session sat idle'))).toHaveLength(3)
expect(w.adds.at(-1)).toContain(WT2)
expect(w.prompts.at(-1)).toContain('Milestone #2')
for (const n of w.notifies) expect(n).not.toContain('/auto-claude status')
})
})
Expand Down
31 changes: 31 additions & 0 deletions auto-claude/hooks/guard.ts
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,37 @@ export function deploysSomething(command: string): boolean {
return command.split(/&&|\|\||[;|&\n`()]|\$\(/).some(segment => DEPLOY.test(segment) && !readOnly(segment))
}

// Waiting inside a turn: a run never rests, and what it waits for (CI, a
// merge, a deploy) the driver watches itself. A sleep of at least
// WAIT_MAX_S, or watching CI until it ends, is refused; short sleeps (a
// check that waits for a server to come up) pass. Judged on tokens per piece.
export const WAIT_MAX_S = 60
const UNIT_S: Record<string, number> = { '': 1, s: 1, m: 60, h: 3600, d: 86400 }

function sleepSeconds(tokens: readonly string[]): number {
let total = 0
for (const t of tokens) {
const m = t.match(/^(\d+(?:\.\d+)?)([smhd]?)$/)
if (m === null) return Number.POSITIVE_INFINITY
total += Number(m[1]) * UNIT_S[m[2] ?? '']!
}
return total
}

export function waitsLong(raw: string): boolean {
return stripProse(raw)
.split(/&&|\|\||[;|&\n`()]|\$\(/)
.some(segment => {
const tokens = segment.trim().split(/\s+/).filter(t => t !== '' && !/^[A-Za-z_][A-Za-z0-9_]*=/.test(t))
const [tool, ...rest] = tokens
// No literal argument left in its piece: a computed duration, `sleep $((60*5))`.
if (tool === 'sleep') return rest.length === 0 || sleepSeconds(rest) >= WAIT_MAX_S
if (tool !== 'gh') return false
if (rest[0] === 'run' && rest[1] === 'watch') return true
return rest[0] === 'pr' && rest[1] === 'checks' && rest.includes('--watch')
})
}

function isSafeRmTarget(target: string, worktree: string): boolean {
const bare = target.replace(/^['"]|['"]$/g, '')
if (bare.includes('..') || bare.startsWith('~') || bare.includes('$') || bare === '*' || bare === '.' || bare === '/') {
Expand Down
Loading
Loading