**Tell your agent to start working. Walk away. Come back to finished work.**
AutoGrind is a skill for AI coding agents that makes them work _continuously and autonomously_, grinding through improvements, fixes, tests, and polish in repeating cycles until _you_ say stop. No hand-holding. No "should I continue?" No stopping because the TODO list looks empty.
Works for any long-running workflow: code, ML, research, design, writing.
Compatible with the [Agent Skills](https://agentskills.io) open standard; works across Claude Code, Codex, Gemini CLI, OpenCode, Cursor, Windsurf, Roocode, Cline, Trae, Kimi Code, GitHub Copilot, Goose, AmpCode, Kilo, Kiro, Factory, Hermes Agent, and any skills-compatible agent. Each mechanism is grounded in published AI/ML research; see [RESEARCH.md](RESEARCH.md).
English | [简体中文](README.zh.md)
---
## Install
Paste this into any agent chat:
```
Please install the AutoGrind skill from https://github.com/ttttonyhe/autogrind.
Clone the repo, install the skill to the right location for my agent environment,
and confirm it is ready to use.
```
If you use Claude Code, the native plugin is the preferred install. It enables automatic updates and integrates natively with Claude Code's plugin system:
```bash
/plugin marketplace add ttttonyhe/autogrind
/plugin install autogrind@autogrind
/reload-plugins
```
For Codex native plugin install, see [PLUGIN.md](PLUGIN.md).
---
## Usage
Invoke via the slash command:
```bash
/autogrind
```
If you installed via Claude Code plugin, then invoke via the slash command:
```bash
/autogrind:start
```
Remember to enable unrestricted tool use so AutoGrind can run commands, read files, and commit without per-call permission prompts. For example:
```bash
claude --dangerously-skip-permissions
```
Without this, AutoGrind pauses on every tool call. It works, but defeats the purpose.
<details>
<summary>Manual CLI installation</summary>
### Universal (all agents)
All agentskills.io-compatible agents discover skills from `~/.agents/skills/`. One install, all agents:
```bash
# Stable install — clone directly to the skills location
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.agents/skills/autogrind
# Or symlink from an existing clone (live updates)
git clone https://github.com/ttttonyhe/autogrind.git
ln -sfn "$(pwd)/autogrind" ~/.agents/skills/autogrind
```
---
### Claude Code
```bash
# Stable install — clone directly to the skills location
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.claude/skills/autogrind
# Or symlink from an existing clone (live updates)
ln -sfn "$(pwd)" ~/.claude/skills/autogrind
```
**Invoke:** `/autogrind` or `"keep working, don't stop"`
Optional native plugin (invoke with `/autogrind:start`):
```bash
claude plugin marketplace add ttttonyhe/autogrind && claude plugin install autogrind@autogrind
```
---
### Codex
Preferred native plugin path: open this repo in Codex, open `plugins`, and install `autogrind` from the AutoGrind marketplace. Full instructions: [PLUGIN.md](PLUGIN.md).
For direct skill install or local authoring/testing, the raw skill still works:
```bash
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.agents/skills/autogrind
```
Codex discovers raw skills automatically from `~/.agents/skills/`. Enable full auto-approval in your Codex config so tool calls are not gated on confirmation.
**Invoke:** `"autogrind this project"` or `"keep working, don't stop"`
---
### Gemini CLI
```bash
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.gemini/skills/autogrind
# Or use the universal path: ~/.agents/skills/autogrind
```
Gemini CLI discovers skills automatically from `~/.gemini/skills/` — no GEMINI.md entry required. For local development, use `gemini skills link` to symlink.
**Invoke:** `gemini "autogrind this project, don't stop until I say so"`
---
### OpenCode
```bash
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.agents/skills/autogrind
# Or: ~/.claude/skills/autogrind (OpenCode checks both)
```
OpenCode discovers skills automatically — no AGENTS.md entry required.
**Invoke:** `opencode "autogrind this project, keep going until I say stop"`
---
### Cursor
```bash
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.cursor/skills/autogrind
# Or use the universal path: ~/.agents/skills/autogrind
```
Enable auto-run for terminal commands in Cursor settings.
**Invoke:** `"Keep working on this project autonomously. Don't stop."`
---
### Windsurf
```bash
# Preferred path
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.codeium/windsurf/skills/autogrind
# Or universal path
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.agents/skills/autogrind
```
**Invoke:** `"autogrind this project, don't stop"`
---
### Roocode
```bash
# Preferred path
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.roo/skills/autogrind
# Or universal path
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.agents/skills/autogrind
```
**Invoke:** `"Keep working, don't stop"`
---
### Cline
```bash
# Preferred path
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.cline/skills/autogrind
# Or universal path
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.agents/skills/autogrind
```
**Invoke:** `"autogrind this project, keep going"`
---
### Trae
```bash
# Preferred path
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.trae/skills/autogrind
# Or universal path
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.agents/skills/autogrind
```
**Invoke:** `"autogrind this, don't stop"` or `/autogrind`
---
### Kimi Code
```bash
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.config/agents/skills/autogrind
# Or project-level
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git .kimi/skills/autogrind
```
**Invoke:** `/skill:autogrind` or `"keep working, don't stop"`
---
### GitHub Copilot
```bash
# Preferred paths
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.copilot/skills/autogrind
# Or universal path
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.agents/skills/autogrind
```
Pair with a `.github/copilot-instructions.md` file to give Copilot project context.
**Invoke:** `"autogrind mode — keep working autonomously"` or `/autogrind`
---
### Goose
```bash
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.agents/skills/autogrind
```
**Invoke:** `"autogrind this project, keep going"`
---
### AmpCode
```bash
# Preferred path
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.config/agents/skills/autogrind
# Or universal path
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.agents/skills/autogrind
```
**Invoke:** `"autogrind this, don't stop"`
---
### Kilo / Kiro / Factory
```bash
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.agents/skills/autogrind
```
All support the agentskills.io universal path. Install once, invoke directly.
**Invoke:** `"Keep working on this project. Don't stop."` or `"autogrind"`
---
### Hermes Agent (NousResearch)
```bash
git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.agents/skills/autogrind
```
**Invoke:** `"autogrind this, keep going"`
</details>
---
## Update
Paste this into any agent chat:
```
Please update the AutoGrind skill to the latest version from https://github.com/ttttonyhe/autogrind.
```
If you installed via Claude Code plugin, update the marketplace first (to fetch the latest version catalog), then update the plugin:
```bash
claude plugin marketplace update autogrind
claude plugin update autogrind@autogrind
```
<details>
<summary>Manual update</summary>
```bash
# If installed as symlink — pull in the source repo.
# If installed via git clone, pull inside the install location:
cd ~/.claude/skills/autogrind && git pull # Claude Code
cd ~/.agents/skills/autogrind && git pull # Universal / Codex / Gemini / OpenCode / Cursor
```
</details>
---
## The Grind Cycle
```mermaid
flowchart TD
INIT["INIT (once)\nDetect guidance files\nExtract goals and conventions"]
OV["1. OVERVIEW\nAssess project state"]
UN["2. UNDERSTAND\nReview relevant work and history"]
PL["3. PLAN\nPrioritized tasks + frontier scan"]
WK["4. WORK\nExecute, validate, persist"]
RF["5. REFLECT\nGrounded signals + heuristics"]
PA["PAUSE 60s\nAnnounce, wait, continue"]
ST{"Explicit stop\nsignal?"}
STOP(["STOP"])
NEVER["NEVER stop\non your own"]
INIT --> OV --> UN --> PL --> WK --> RF --> PA --> ST
ST -->|yes| STOP
ST -->|no, always| OV
ST -.->|tempted to stop| NEVER
```
Every Reflect phase: checks verifiable signals first (test results, metrics, build status), evaluates core deliverable progress, scans quality dimensions (coverage, error handling, docs, performance, UX, observability, security), detects stuck loops and shifts focus, and extracts a transferable heuristic for the next cycle. There is always a weakest dimension.
After each cycle, AutoGrind pauses 60 seconds so you can interrupt. If you do nothing, it continues automatically.
---
## FAQ
**When does it stop? What if my project is already complete?**
AutoGrind stops only when you explicitly tell it to: "stop", "halt", "pause", "that's enough", or any clear termination request. It never stops on its own.
If your project feels done, AutoGrind will find the next improvement: coverage gaps, missing documentation, performance wins, edge cases, polish. The Reflect phase evaluates against a checklist of quality dimensions and always surfaces something. Say "stop" when _you_ are satisfied.
**Will it run destructive commands? Will I wake up to a broken system?**
AutoGrind prioritizes reversible, tracked changes. Every code change gets committed to git, so you have a full undo trail. It does not intentionally run destructive operations (rm -rf, force push, DROP TABLE) as part of its workflow.
That said, AutoGrind runs code, edits files, and commits changes autonomously. Recommended safeguards:
- Start from a clean git working tree so all changes are tracked and easy to review
- When you return, run `git log` before deploying anything
- For sensitive environments, use your agent's permission controls to restrict which commands it can run
**Will context compaction break AutoGrind?**
No. Each cycle begins with an Overview phase that re-reads project state from scratch: git history, test output, file structure, open issues. AutoGrind does not depend on remembering previous cycles. Long sessions with multiple context compactions work fine.
---
## Use Cases
**Go to bed. Wake up to finished work.**
```
You: autogrind this, i'm going to bed
Agent: [starts grinding]
cycle 1 - fixed broken import, added 12 tests
cycle 2 - documented all exported functions
cycle 3 - reduced DB query count by 40%
cycle 4 - added input validation, edge case tests
...
You: [8 hours later] stop
```
**ML / data science** - point it at a training script. It runs experiments, inspects metrics, adjusts hyperparameters, re-runs, and iterates. Come back to a full experiment trail and an improved model.
**Academic research** - grind through a literature review, fill methodology gaps, expand weak sections, cross-check citations. Each cycle improves the manuscript.
**Codebase cleanup** - point it at a messy repo. It fixes linting, improves coverage, fills doc gaps, and refactors the worst offenders, in priority order, with meaningful commits.
**Design iteration** - work through a revision backlog: consistency checks, accessibility improvements, copy edits, spacing fixes. Any workflow where "keep improving until told to stop" is the right mode.
---
## What Gets Committed
AutoGrind commits after each logical change, with a meaningful message. When you return, `git log` tells the full story.
```
$ git log --oneline
f3a1b2c Reduce N+1 queries in UserRepository.findByOrg()
e8d4c91 Test: cover AuthService.refreshToken() null and expired cases
b7a3f52 Fix: null pointer dereference in SessionManager.cleanup()
a91e2b4 Docs: add JSDoc to all public ApiClient methods
9c4d718 Refactor: extract retry logic from ApiClient into RetryHandler
8b2f1e7 Test: add integration tests for /auth/refresh endpoint
```
---
## How It Knows What to Work On
On first run, AutoGrind scans for guidance files in order:
1. `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / `.cursorrules`
2. `opencode.md`
3. `README.md`
It extracts your project goals, tech stack, conventions, and known issues. If none exist, it infers from directory structure, package files, and test output.
Write a `CLAUDE.md` describing what matters. AutoGrind will respect it.
---
## Development
```bash
# Validate skill structure
npx skills-ref validate skills/autogrind
# Generate agent responses for a full eval run (with_skill and without_skill)
python3 tests/generate-responses.py --all \
--iteration-dir autogrind-workspace/iteration-N/ \
--timeout 300 --workers 1
# Grade a single eval against an agent response
python3 tests/grade-evals.py --response <response-file> --eval-id <N>
# Grade all evals (responses-dir must contain eval-<N>.txt files)
python3 tests/grade-evals.py --all --responses-dir <dir> --config with_skill
# Parallel grading for faster batch runs (5-10 workers recommended)
python3 tests/grade-evals.py --all --responses-dir <dir> --workers 8
# Blind holistic comparison between two responses (with_skill vs without_skill)
python3 tests/blind-compare.py --response-a <file-a> --response-b <file-b> --eval-id <N>
# Aggregate grading results into benchmark.json
python3 tests/aggregate-benchmark.py --iteration-dir <workspace/iteration-N/>
# Classify eval pass/fail patterns to identify what needs attention
python3 tests/analyze-failures.py --iteration-dir <workspace/iteration-N/>
```
Evals are in `evals/evals.json` (69 cases) with a JSON schema at `evals/evals.schema.json` for IDE validation. Description trigger queries for optimizing the skill description are in `evals/train_queries.json` and `evals/validation_queries.json`. See `CLAUDE.md` for the full eval workflow: spawning runs, grading, blind comparison, aggregation, analysis, human review, and iteration.
When evals fail: first ask whether the skill implementation needs improvement. Fix the skill before modifying assertions. Assertions change only when genuinely misclassifying correct behavior.