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 .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@
},
{
"name": "auto-claude",
"description": "Unattended run of a repository, to the end state live: Claude plans the long-term goal, milestones and deploy; the built-in loop builds each in a worktree and judges it; auto-claude pushes, opens PRs, merges when CI is green, deploys and smoke-checks, and a watchdog repairs or routes around stalls until the final check passes.",
"description": "Unattended run of a repository, to the end state live: Claude plans the long-term goal, milestones and deploy; the built-in loop builds each in a worktree and judges it; auto-claude pushes, opens PRs, merges when CI is green, deploys and smoke-checks, and a watchdog repairs or routes around stalls until the final check passes. With --always-on it then stands by and wakes for new cycles (Linear, live smoke check, default-branch CI, labelled GitHub issues).",
"author": {
"name": "unohee"
},
Expand Down
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.3.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; since 1.3.0 a line can wait on a training run or cache build (`:: after:`, `wait_until`) without ending the run |
| [auto-claude](auto-claude/) | 1.4.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; since 1.3.0 a line can wait on a training run or cache build (`:: after:`, `wait_until`) without ending the run; since 1.4.0 `--always-on` stands by after the final check and wakes for new cycles from Linear, the live smoke check, the default branch's CI and labelled GitHub issues |
| [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
34 changes: 32 additions & 2 deletions auto-claude/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "auto-claude",
"version": "1.3.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).",
"version": "1.4.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. With --always-on it does not end there: it stands by with no model turn and wakes for a new cycle when Linear, the live smoke check, the default branch's CI or a labelled GitHub issue gives it work (1.4.0). Absorbs goal-mode's loop (1.0.0).",
"author": {
"name": "unohee"
},
Expand Down Expand Up @@ -43,6 +43,36 @@
"title": "CI poll interval (s)",
"description": "How often the driver looks at the loop's log and the open PR",
"default": 30
},
"alwaysOn": {
"type": "boolean",
"title": "Always on by default",
"description": "Every /auto-claude start stands by after its final check passes, as with --always-on (--once opts a run out)",
"default": false
},
"healthEveryMin": {
"type": "number",
"title": "Standby smoke check interval (min)",
"description": "While standing by, how often the plan's Smoke check runs; 2 failures in a row queue a repair and wake the run",
"default": 30
},
"githubEveryMin": {
"type": "number",
"title": "Standby GitHub poll interval (min)",
"description": "While standing by, how often the default branch's CI runs and labelled issues are read (github CI mode only)",
"default": 10
},
"issueLabel": {
"type": "string",
"title": "GitHub issue label",
"description": "Open issues with this label become queue lines of an always-on run (empty: issues are not read). Only people with triage access can label, so the label is the trust gate",
"default": "auto-claude"
},
"maxMergesPerDay": {
"type": "number",
"title": "Max merges per 24 h (always on)",
"description": "An always-on run does not wake while the last 24 h already hold this many merges; maxMerges and maxHours count per cycle",
"default": 20
}
}
}
25 changes: 24 additions & 1 deletion auto-claude/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@ An unattended run of one repository, through to what it built being live. Give i

```
/auto-claude start [aim] # e.g. /auto-claude start finish the CLI and its docs
/auto-claude start --always-on [aim] # the same, then stand by and wake for new work
/auto-claude start --queue # build .claude/goals.md as it is: branches only, nothing shipped
/auto-claude standby # a finished run (or the one going) stands by from now on
/auto-claude status | stop | resume
```

Expand Down Expand Up @@ -50,6 +52,27 @@ goal-mode merged into auto-claude in 1.0.0 (see "From goal-mode" below). Its loo
- 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`).

## Always on

With `--always-on` (or the `alwaysOn` option), a run does not end when its final check passes. It **stands by**: still on, but with no model turn, while the driver polls what can give it work. Each new thing becomes a queue line, and a queue line wakes the run for a new **cycle**. The design follows [Building always-on agents](https://claude.com/resources/articles/building-always-on-agents): sleep without tokens, wake on events and timers, keep memory outside the conversation, send little.

| source | polled | becomes |
| --- | --- | --- |
| Linear (mapped project) | every 10 min, as during a run | `- [ ] [AX-12] …` (see "Linear") |
| The plan's `Smoke check:` | every `healthEveryMin` (30) | 2 failures in a row: the deploy repair line, built from the default branch first |
| The default branch's CI (github mode) | every `githubEveryMin` (10), and at once on entering standby | a failed run on the branch's current tip: `- [ ] [ci:<run>] The "<workflow>" workflow passes on main again …` |
| Open GitHub issues labelled `issueLabel` (`auto-claude`) | with the CI poll | `- [ ] [gh#12] <title>: what GitHub issue #12 asks is resolved on this branch …`; closed with a comment when it merges |

- **Dedupe.** Each event has an id (`ci:<run>`, `gh#<n>`) and a stamp; an id is queued once, at most 5 lines per poll. A GitHub issue's later changes (comments, edits) queue nothing.
- **Trust.** Labelling needs triage access, so the label is the gate: an issue is work when someone who may label it says so, once. Only its number and title go into the line, with `::` and brackets removed, so a title cannot add a check or a base. The model reads the issue itself while building; its body is still third-party text, so label only issues whose body you would hand the run. Peer messages and webhook text do not wake a run.
- **`--once`** opts a single start out when `alwaysOn` is the default.
- **Waking.** Only when the session has had no turn for 2 min: a person may use the session while it stands by. A cycle builds, ships and deploys like any run, without a new planning round; its final check passing stands it by again. A failing one replans, as a run does.
- **Standing by owns nothing.** The guards and the unattended policy are off, `.claude/auto-claude.on` says `on: false, phase: standby` (harness's Linear rules apply again), and the watchdog's idle notices are quiet.
- **Caps.** `maxMerges` and `maxHours` count per cycle; standby time counts toward neither. `maxMergesPerDay` (20) holds a wake back while the last 24 h hold that many merges, told once. 3 deploys failing in a row still stop the run.
- **Memory.** Each cycle adds one line under `## Cycles` in `auto-plan.md`: what woke it, what merged, was held and deployed. On entering standby the session is compacted once (when its context is 30% full or more), keeping the goal, decisions and cycles.
- **Quiet.** In standby a person is told only of a wake (and why), a cycle's end, a failing smoke check or GitHub poll, and the daily cap.
- **Limits.** The worker is the session: if it exits, nothing polls until `/auto-claude resume` in a session (other sessions report it orphaned). An external supervisor, Remote Control or webhook inboxes, and answering a deferred milestone are not part of this.

## Deploying

The run's end is what it built **live**: merged, deployed and smoke-checked. A plan that leaves the deploy or the release to the person is not accepted.
Expand Down Expand Up @@ -169,4 +192,4 @@ Measured in ArtifactNet (2026-11-09 to 11-15): lines carried prose start conditi
- **Session goals** (`set_goal`, `/goal-mode set|auto|clear` and the outcome nudges) are gone. Use Claude Code's `/goal` and `ProposeGoal`.
- **A run already going** when 1.0 loads keeps its milestone. The loop's state lived in goal-mode's store, which this plugin cannot read, so the open milestone is found again from the last `start` in `.claude/goal-loop.log` and prompted again. New branches number above the highest existing `goal/NN-*`.

Options: `ciMode` (`auto` | `github` | `local`), `maxRounds`, `maxMerges`, `maxHours`, `maxWaitHours` and `ciPollSec`.
Options: `ciMode` (`auto` | `github` | `local`), `maxRounds`, `maxMerges`, `maxHours`, `maxWaitHours`, `ciPollSec`, and for always-on runs `alwaysOn`, `healthEveryMin`, `githubEveryMin`, `issueLabel` and `maxMergesPerDay`.
114 changes: 114 additions & 0 deletions auto-claude/hooks/auto.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,11 @@ function world(on: On, store: Record<string, unknown> = {}) {
rebaseFails: false,
// Exits of particular `bash -lc <command>` runs (a wait's after and alive), over checkExit.
cmdExit: new Map<string, number>(),
// Standby: `gh issue list` for the label, the default branch tip, context fill and compactions.
issueList: '[]',
tip: 'tip',
contextPercent: 50,
compacts: 0,
clock: mock.clock(on, { now: 1_000 }),
}
const removed = (path: string) => [...w.gone].some(g => path === g || path.startsWith(`${g}/`))
Expand All @@ -99,6 +104,11 @@ function world(on: On, store: Record<string, unknown> = {}) {
w.notifies.push(e.text)
return { value: { isSent: true as const, channel: 'terminal_bell' as const } }
})
on('session.usage', () => ({ value: { context: { window: 200_000, percent: w.contextPercent } } as never }))
on('session.compact', () => {
w.compacts++
return { skip: 'test' } as never
})
on('env.get', () => ({ value: '/home' }))
on('fs.read', (_, e) => {
const t = w.files.get(e.path)
Expand Down Expand Up @@ -175,6 +185,8 @@ function world(on: On, store: Record<string, unknown> = {}) {
return ok()
}
if (a.startsWith('gh run list')) return ok(w.runList)
if (a.startsWith('gh issue list')) return ok(w.issueList)
if (/ rev-parse (origin\/)?main$/.test(a)) return ok(`${w.tip}\n`)
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 w.branchGone ? ok('', 1) : ok(`tip-of-${String(e.argv.at(-1)).replace(/\^\{commit\}$/, '')}\n`)
Expand Down Expand Up @@ -1461,3 +1473,105 @@ describe('waits on compute (:: after:, wait_until)', () => {
expect(w.prompts).toEqual([])
})
})

describe('always on (standby)', () => {
const SMOKE = 'curl -fsS http://localhost:8080/health'
// Plans an always-on run and builds both milestones until it stands by.
async function standing($: Engine, w: W, plan = PLAN_DEPLOY) {
await $.session.start({ cwd: '/repo', surface: 'terminal', isInteractive: true })
expect((await cmd($, 'start --always-on')).text).toContain('Always on')
w.files.set('/repo/.claude/auto-plan.md', plan)
w.files.set(GOALS, QUEUE)
await ready($)
await w.clock.advance(1_200)
await meet($, w)
await w.clock.advance(TICK)
await meet($, w)
for (let i = 0; i < 3; i++) await w.clock.advance(TICK)
}

test('a passing final check stands by: on, owning nothing, compacted once, quiet while nothing happens', { timeoutMs: 60_000 }, async ($, on) => {
const w = world(on)
await standing($, w)
expect(w.notifies.at(-1)).toContain('the final check passed after 1 round(s); standing by')
expect(w.files.get('/repo/.claude/auto-plan.md')).toContain('## Result')
expect((await cmd($, 'status')).text).toContain('auto-claude on · phase standby')
expect(JSON.parse(w.files.get('/repo/.claude/auto-claude.on') ?? '{}')).toMatchObject({ on: false, phase: 'standby' })
// The person may use the session: no refusals, no unattended policy.
expect((await $.tool.call({ tool: 'AskUserQuestion', questions: [] } as never)).deny).toBeUndefined()
expect((await compose($)).sections.some((x: { id: string }) => x.id === 'auto-claude:policy')).toBe(false)
const told = w.notifies.length
const prompts = w.prompts.length
await w.clock.advance(20 * MIN)
expect(w.compacts).toBe(1)
expect(w.notifies.length).toBe(told)
expect(w.prompts.length).toBe(prompts)
})

test('a smoke check failing twice in standby queues a repair, wakes cycle 1, ships it and stands by again with a cycle line', { timeoutMs: 120_000 }, async ($, on) => {
const w = world(on)
await standing($, w)
w.cmdExit.set(SMOKE, 7)
await w.clock.advance(31 * MIN)
expect(parseQueue(w.files.get(GOALS) ?? '').filter(i => i.mark === ' ')).toHaveLength(0)
await w.clock.advance(31 * MIN)
expect(w.notifies.some(n => n.includes('failed 2 times in a row while standing by'))).toBe(true)
// Smoke-checked as the deploy does: in a fresh checkout of the default branch.
expect(w.runs).toContain('git -C /repo worktree add --detach /repo/worktrees/auto-health origin/main')
expect(w.notifies.some(n => n.includes('cycle 1 starts'))).toBe(true)
expect(w.prompts.at(-1)).toContain('The cause of the failed deploy is found and fixed')
w.cmdExit.delete(SMOKE)
await meet($, w)
for (let i = 0; i < 3; i++) await w.clock.advance(TICK)
expect((await cmd($, 'status')).text).toContain('phase standby')
expect(w.files.get('/repo/.claude/auto-plan.md')).toMatch(/## Cycles\n\n- cycle 1, .*: woke for The cause of the failed deploy is found ; merged 1, held 0, deployed 1/)
})

test('github: a red default-branch tip and a labelled issue are queued once, wake a cycle, and the issue is closed on merge', { timeoutMs: 120_000 }, async ($, on) => {
const w = world(on)
w.github = true
await standing($, w, PLAN)
// A person is in the session: no wake until it has been quiet for 2 min.
await turnStart($)
w.runList = JSON.stringify([{ databaseId: 5, headSha: 'tip', conclusion: 'failure', workflowName: 'CI' }])
w.issueList = JSON.stringify([{ number: 3, title: 'docs :: check: true', updatedAt: 'u1' }])
await w.clock.advance(11 * MIN)
const queue = parseQueue(w.files.get(GOALS) ?? '').filter(i => i.mark === ' ')
expect(queue.map(i => i.condition.slice(0, 7))).toEqual(['[ci:5] ', '[gh#3] '])
expect(queue.every(i => i.check === undefined)).toBe(true)
expect((await cmd($, 'status')).text).toContain('phase standby')
await turnEnd($)
await w.clock.advance(3 * MIN)
expect(w.notifies.some(n => n.includes('woke for ci:5, gh#3: cycle 1 starts'))).toBe(true)
await w.clock.advance(11 * MIN)
expect(parseQueue(w.files.get(GOALS) ?? '').filter(i => i.condition.startsWith('[gh#3]'))).toHaveLength(1)
await meet($, w)
await w.clock.advance(TICK)
await meet($, w)
for (let i = 0; i < 3; i++) await w.clock.advance(TICK)
expect(w.runs.some(r => r.startsWith('gh issue close 3 --repo o/r --comment [auto-claude] Resolved by PR #7'))).toBe(true)
for (const call of w.runs.filter(a => /^gh (run|issue) list/.test(a))) expect(call).toContain('--repo o/r')
expect((await cmd($, 'status')).text).toContain('phase standby')
})

test('stop and resume in standby; standby turns a finished run always on', { timeoutMs: 60_000 }, async ($, on) => {
const w = world(on)
await $.session.start({ cwd: '/repo', surface: 'terminal', isInteractive: true })
await cmd($, 'start')
w.files.set('/repo/.claude/auto-plan.md', PLAN)
w.files.set(GOALS, QUEUE)
await ready($)
await w.clock.advance(1_200)
await meet($, w)
await w.clock.advance(TICK)
await meet($, w)
for (let i = 0; i < 3; i++) await w.clock.advance(TICK)
expect((await cmd($, 'status')).text).toContain('phase done')
expect((await cmd($, 'standby')).text).toContain('Standing by')
expect((await cmd($, 'status')).text).toContain('phase standby')
await cmd($, 'stop')
expect((await cmd($, 'status')).text).toContain('auto-claude off · phase stopped')
expect((await cmd($, 'resume')).text).toContain('Resumed: standing by')
expect((await cmd($, 'status')).text).toContain('phase standby')
})
})
Loading
Loading