gemini-autoresearch

<div align="center">
<img src="images/banner.png" width="1200" alt="gemini-autoresearch banner">
</div>

<div align="center">

```
╔═══════════════════════════════════════════════════════════════╗
║                                                               ║
║          gemini-autoresearch                                  ║
║                                                               ║
║     Set a goal. Walk away. Wake up to results.                ║
║                                                               ║
║     Your AI works all night so you don't have to.            ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝
```

[![Gemini CLI Skill](https://img.shields.io/badge/Gemini_CLI-Skill-4285F4?logo=google&logoColor=white)](https://github.com/google-gemini/gemini-cli)
[![Antigravity IDE](https://img.shields.io/badge/Antigravity-IDE-8B5CF6?logoColor=white)](https://antigravity.dev)
[![License: MIT](https://img.shields.io/badge/License-MIT-22C55E.svg)](LICENSE)
[![Hindi](https://img.shields.io/badge/Hindi-README-blue?style=flat-square)](docs/i18n/README_HI.md)
[![Bengali](https://img.shields.io/badge/Bengali-README-green?style=flat-square)](docs/i18n/README_BN.md)
[![Chinese](https://img.shields.io/badge/Chinese-README-red?style=flat-square)](docs/i18n/README_ZH.md)
[![Japanese](https://img.shields.io/badge/Japanese-README-black?style=flat-square)](docs/i18n/README_JA.md)
[![French](https://img.shields.io/badge/French-README-blue?style=flat-square)](docs/i18n/README_FR.md)
[![Spanish](https://img.shields.io/badge/Spanish-README-yellow?style=flat-square)](docs/i18n/README_ES.md)
[![Portuguese](https://img.shields.io/badge/Portuguese-README-green?style=flat-square)](docs/i18n/README_PT.md)
[![Russian](https://img.shields.io/badge/Russian-README-white?style=flat-square)](docs/i18n/README_RU.md)

**[What is this?](#what-is-this)** · **[5-minute install](#5-minute-install)** · **[How it works](#how-it-works)** · **[Commands](#commands)** · **[Examples](#examples)** · **[Why Gemini?](#why-gemini-specifically)** · **[Contributing](CONTRIBUTING.md)**

</div>

---

## What is this?

**gemini-autoresearch** turns [Gemini CLI](https://github.com/google-gemini/gemini-cli) and [Antigravity IDE](https://antigravity.dev) into an autonomous improvement engine — for anything with a measurable outcome.

You describe what you want to improve. Gemini runs hundreds of small experiments overnight. It keeps every improvement and automatically reverses anything that makes things worse. You wake up to a log of exactly what happened.

> **Not a developer?** That's fine. If you use Antigravity IDE to help with your work — writing, marketing, operations, content — this skill works for you too. [See non-technical examples →](#for-non-developers)

---

## The big picture

Think of it like this. Normally when you use an AI assistant:

```
You describe a problem → AI gives you an answer → Done (one shot)
```

With gemini-autoresearch:

```
You set a goal → AI runs 100 experiments overnight → You keep every gain
       ↑                                                        |
       └────────────────── each run smarter than the last ──────┘
```

The difference is that it never stops at one answer. It iterates — trying things, measuring results, keeping what works, throwing out what doesn't — until you tell it to stop or it hits your goal.

---

## How it works

Every iteration follows the same loop, running forever until you interrupt:

```
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│  1. READ        Review current state, git history, past lessons │
│  2. THINK       Form ONE specific hypothesis to test            │
│  3. CHANGE      Make ONE focused change                         │
│  4. SAVE        Git commit before testing (safe rollback point) │
│  5. MEASURE     Run Verify — did the metric improve?            │
│  6. PROTECT     Run Guard  — did anything else break?           │
│  7. DECIDE      Both pass → KEEP  /  Either fails → REVERT      │
│  8. LOG         Record what happened and why                    │
│  9. LEARN       Every 5 wins → write a lesson for future runs   │
│                                                                 │
│  ↑_________________________REPEAT FOREVER____________________↑  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Verify vs Guard — what is the difference?

This dual-gate system makes gemini-autoresearch safer than any other autoresearch skill:

| | Verify | Guard |
|---|---|---|
| **Question** | "Did I make progress?" | "Did I break anything?" |
| **Example** | Did test coverage go up? | Do types still compile? |
| **If it fails** | Revert immediately | Rework (max 2 tries), then revert |
| **Required?** | Yes | Optional but strongly recommended |

**Why this matters:** Without Guard, an AI chasing test coverage could silently introduce TypeScript errors across 50 iterations. With Guard, any change that breaks types gets reverted — even if it improved coverage. You wake up to clean working code, not just higher numbers.

---

## 5-minute install

### For Gemini CLI

```bash
# 1. Clone this repo
git clone https://github.com/supratikpm/gemini-autoresearch.git

# 2a. Install globally — works in ALL your projects
cp -r gemini-autoresearch/skills/autoresearch ~/.gemini/skills/autoresearch

# 2b. Or install for this project only
cp -r gemini-autoresearch/skills/autoresearch .gemini/skills/autoresearch

# 3. Enable in Gemini CLI
# Open Gemini CLI → type /settings → enable Agent Skills
```

### For Antigravity IDE

```bash
cp -r gemini-autoresearch/skills/autoresearch .agents/skills/autoresearch
```

Antigravity auto-discovers skills in `.agents/skills/` — no settings change needed. Just describe your goal and it picks up the skill automatically.

### Verify it is working

```
/skills
```

You should see `autoresearch` in the list.

---

## Commands

### `/autoresearch` — the main loop

```
/autoresearch
Goal:   <what you want to improve>
Scope:  <files or folders the AI may change>
Metric: <what to measure, and whether higher or lower is better>
Verify: <command that outputs the metric>
Guard:  <command that must always pass — optional>
```

### `/autoresearch:plan` — do not know where to start?

Just describe your goal in plain English. Gemini scans your project, detects your tech stack, proposes the full config, runs a dry run, and hands you the ready-to-run command.

```
/autoresearch:plan make my app faster
/autoresearch:plan improve test coverage
/autoresearch:plan reduce my Docker image size
```

### `/autoresearch:ship` — pre-flight before releasing

Runs a full checklist before you ship: tests, types, lint, bundle size, secrets scan, dependency audit. If anything fails, it runs an autoresearch loop to fix it automatically.

```
/autoresearch:ship
/autoresearch:ship --dry-run      ← report only, no fixes
/autoresearch:ship --fast         ← skip slow checks
```

### `/autoresearch:debug` — something is broken

Autonomous root cause analysis. Reproduces the failure, isolates the cause, fixes it, verifies the fix holds.

```
/autoresearch:debug the auth tests are failing
/autoresearch:debug TypeError: Cannot read property 'id' of undefined
/autoresearch:debug CI is failing on the build step
```

### `/autoresearch:security` — find vulnerabilities

Full STRIDE and OWASP security audit. Every finding requires code evidence. Optional auto-fix for confirmed critical and high findings.

```
/autoresearch:security
/autoresearch:security --fix                 ← auto-fix confirmed findings
/autoresearch:security --fail-on critical    ← CI gate mode
```

### Overnight headless mode

```bash
gemini \
  --prompt "Start autoresearch. Goal: reduce bundle size below

[truncated…]