autogrind

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 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.

English | 简体中文

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:

/plugin marketplace add ttttonyhe/autogrind
/plugin install autogrind@autogrind

/reload-plugins

For Codex native plugin install, see PLUGIN.md.

Usage

Invoke via the slash command:

/autogrind

If you installed via Claude Code plugin, then invoke via the slash command:

/autogrind:start

Remember to enable unrestricted tool use so AutoGrind can run commands, read files, and commit without per-call permission prompts. For example:

claude --dangerously-skip-permissions

Without this, AutoGrind pauses on every tool call. It works, but defeats the purpose.

Universal (all agents)

All agentskills.io-compatible agents discover skills from ~/.agents/skills/. One install, all agents:

# 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

# 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):

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.

For direct skill install or local authoring/testing, the raw skill still works:

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

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

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

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

# 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

# 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

# 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

# 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

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

# 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

git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.agents/skills/autogrind

Invoke: "autogrind this project, keep going"

AmpCode

# 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

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)

git clone --depth 1 https://github.com/ttttonyhe/autogrind.git ~/.agents/skills/autogrind

Invoke: "autogrind this, keep going"

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:

claude plugin update autogrind@autogrind

# 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

The Grind Cycle

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

# 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.