|
2 | 2 |
|
3 | 3 | > For an overview of all available workflows, see the [main README](../README.md). |
4 | 4 |
|
5 | | -**Iterative optimization agent inspired by [Autoresearch](https://github.com/karpathy/autoresearch) and Claude Code's `/loop`** |
| 5 | +Autoloop has moved to its own repository: **<https://github.com/githubnext/autoloop>** |
6 | 6 |
|
7 | | -The [Autoloop workflow](../workflows/autoloop.md?plain=1) runs on a schedule to autonomously improve target artifacts toward measurable goals. Each iteration proposes a change, evaluates it against a metric, and keeps only improvements. Supports **multiple independent loops** in the same repository. |
8 | | - |
9 | | -## Installation |
10 | | - |
11 | | -```bash |
12 | | -# Install the 'gh aw' extension |
13 | | -gh extension install github/gh-aw |
14 | | - |
15 | | -# Add the workflow to your repository |
16 | | -gh aw add-wizard githubnext/agentics/autoloop |
17 | | -``` |
18 | | - |
19 | | -This walks you through adding the workflow to your repository. |
20 | | - |
21 | | -## How It Works |
22 | | - |
23 | | -```mermaid |
24 | | -graph LR |
25 | | - A[Scheduled Run] --> B[Discover Programs] |
26 | | - B --> C[For Each Program] |
27 | | - C --> D[Review History] |
28 | | - D --> E[Propose Change] |
29 | | - E --> F[Implement on Branch] |
30 | | - F --> G[Run Evaluation] |
31 | | - G --> H{Metric Improved?} |
32 | | - H -->|Yes| I[Create Draft PR] |
33 | | - H -->|No| J[Record & Reject] |
34 | | - I --> K[Update Experiment Log] |
35 | | - J --> K |
36 | | -``` |
37 | | - |
38 | | -## Getting Started |
39 | | - |
40 | | -When you install Autoloop, a **template program file** is added at `.github/autoloop/programs/example.md`. This template has placeholder sections you must fill in — the workflow **will not run** until you do. |
41 | | - |
42 | | -### Setup flow |
43 | | - |
44 | | -```mermaid |
45 | | -graph LR |
46 | | - A[Install Workflow] --> B[Rename & Edit Program] |
47 | | - B --> C[Define Goal, Targets, Evaluation] |
48 | | - C --> D[Remove UNCONFIGURED sentinel] |
49 | | - D --> E[Commit & Push] |
50 | | - E --> F[Loop Begins] |
51 | | -``` |
52 | | - |
53 | | -1. **Install** — `gh aw add-wizard githubnext/agentics/autoloop` |
54 | | -2. **Rename** — Rename `.github/autoloop/programs/example.md` to something meaningful (e.g., `training.md`, `coverage.md`). The filename becomes the program name. |
55 | | -3. **Edit** — Replace the placeholders with your project's goal, target files, and evaluation command. The template includes three complete examples for inspiration. |
56 | | -4. **Activate** — Remove the `<!-- AUTOLOOP:UNCONFIGURED -->` line at the top. |
57 | | -5. **Compile & push** — `gh aw compile && git add . && git commit -m "Configure autoloop" && git push` |
58 | | - |
59 | | -If you forget to edit the template, the first scheduled run will create a GitHub issue reminding you, with a direct link to edit the file. |
60 | | - |
61 | | -### Adding more loops |
62 | | - |
63 | | -To run multiple optimization loops in parallel, just add more `.md` files to `.github/autoloop/programs/`: |
64 | | - |
65 | | -``` |
66 | | -.github/autoloop/programs/ |
67 | | -├── training.md ← optimize model training loss |
68 | | -├── coverage.md ← maximize test coverage |
69 | | -└── build-perf.md ← minimize build time |
70 | | -``` |
71 | | - |
72 | | -Each program runs independently with its own metric tracking, experiment log issue, and PR namespace. Copy the template, fill it in, and push — the next scheduled run picks it up automatically. |
73 | | - |
74 | | -## Configuration |
75 | | - |
76 | | -Each program file in `.github/autoloop/programs/` has three sections: |
77 | | - |
78 | | -### 1. Goal — What to optimize |
79 | | - |
80 | | -Describe the objective in natural language. Be specific about what "better" means. |
81 | | - |
82 | | -### 2. Target — What files can be changed |
83 | | - |
84 | | -List the files the agent is allowed to modify. Everything else is off-limits. |
85 | | - |
86 | | -### 3. Evaluation — How to measure success |
87 | | - |
88 | | -Provide a command to run and a metric to extract. Specify whether higher or lower is better. |
89 | | - |
90 | | -### Example program file |
91 | | - |
92 | | -````markdown |
93 | | -# Autoloop Program |
94 | | - |
95 | | -## Goal |
96 | | - |
97 | | -Optimize the training script to minimize validation loss on CIFAR-10 |
98 | | -within a 5-minute training budget. |
99 | | - |
100 | | -## Target |
101 | | - |
102 | | -Only modify these files: |
103 | | -- `train.py` |
104 | | -- `config.yaml` |
105 | | - |
106 | | -## Evaluation |
107 | | - |
108 | | -```bash |
109 | | -python train.py --epochs 5 && python evaluate.py --output-json results.json |
110 | | -``` |
111 | | - |
112 | | -Metric: `validation_loss` from `results.json`. Lower is better. |
113 | | -```` |
114 | | - |
115 | | -### Customizing the Schedule |
116 | | - |
117 | | -Edit the workflow's `schedule` field. Examples: |
118 | | -- `every 6h` — 4 times a day (default) |
119 | | -- `every 1h` — hourly iterations |
120 | | -- `daily` — once a day |
121 | | -- `0 */2 * * *` — every 2 hours (cron syntax) |
122 | | - |
123 | | -After editing, run `gh aw compile` to update the workflow. |
124 | | - |
125 | | -Note: The schedule applies to the workflow as a whole — all programs iterate on the same schedule. To run programs at different frequencies, you can install the workflow multiple times with different schedules, each pointing to a subset of programs. |
126 | | - |
127 | | -## Usage |
128 | | - |
129 | | -### Automatic mode |
130 | | - |
131 | | -Once at least one configured program exists, iterations run automatically on schedule. Each run processes every configured program: |
132 | | - |
133 | | -1. Reads the program definition and past history |
134 | | -2. Proposes a single targeted change |
135 | | -3. Runs the evaluation command |
136 | | -4. Accepts (creates draft PR) or rejects (logs the attempt) |
137 | | - |
138 | | -### Manual trigger |
139 | | - |
140 | | -```bash |
141 | | -# Run all programs now |
142 | | -gh aw run autoloop |
143 | | - |
144 | | -# Target a specific program |
145 | | -gh aw run autoloop -- "training: try using cosine annealing" |
146 | | - |
147 | | -# If only one program exists, no prefix needed |
148 | | -gh aw run autoloop -- "try batch size 64 instead of 32" |
149 | | -``` |
150 | | - |
151 | | -### Slash command |
152 | | - |
153 | | -Comment on any issue or PR: |
154 | | -``` |
155 | | -/autoloop training: try batch size 64 instead of 32 |
156 | | -``` |
157 | | - |
158 | | -## Experiment Tracking |
159 | | - |
160 | | -Each program gets its own monthly experiment log issue titled `[Autoloop: {program-name}] Experiment Log {YYYY-MM}`. The issue tracks: |
161 | | - |
162 | | -- Current best metric value |
163 | | -- Full iteration history with accept/reject status |
164 | | -- Links to PRs for accepted changes |
165 | | -- Links to GitHub Actions runs |
166 | | - |
167 | | -## Human in the Loop |
168 | | - |
169 | | -- **Review draft PRs** — accepted improvements appear as draft PRs for human review |
170 | | -- **Merge or close** — you decide which optimizations to keep |
171 | | -- **Adjust programs** — edit any program file to change the goal, targets, or evaluation |
172 | | -- **Add/remove loops** — add or delete files in `.github/autoloop/programs/` |
173 | | -- **Steer via slash command** — use `/autoloop {program}: {instructions}` to direct experiments |
174 | | -- **Pause** — disable the workflow schedule to stop all loops, or add the sentinel back to a single program file to pause just that loop |
175 | | - |
176 | | -## Security |
177 | | - |
178 | | -- Runs with read-only GitHub permissions |
179 | | -- Only modifies files listed in each program's Target section |
180 | | -- Never modifies evaluation scripts |
181 | | -- All changes go through draft PRs requiring human approval |
182 | | -- Uses "safe outputs" to constrain what the agent can create |
| 7 | +Please refer to that repository for the latest documentation, installation instructions, and source code. |
0 commit comments