Autoresearch Documentation

Autoresearch is an improvement engine designed for AI agents like Claude Code, OpenCode, or OpenAI Codex. It implements a loop-based autonomous iteration pattern inspired by Karpathy's autoresearch.

By setting a goal and a mechanical metric, the agent runs a continuous loop of:

1. Reviewing state and git history.
2. Making a single focused change.
3. Committing the change.
4. Running mechanical verification (tests, benchmarks, etc.).
5. Keeping improvements or automatically reverting failures via Git.

Version 2.2.0 introduced the Autonomous Orchestrator, which allows you to type a plain-language goal to /autoresearch to automatically classify goals, derive success predicates, and loop through subcommands without manual chaining.

Claude Autoresearch is a Claude Code skill/plugin designed to turn Claude Code into an autonomous improvement engine. It automates repetitive improvement cycles (understand state, make change, verify, decide keep/revert, repeat) by using a goal-driven approach with mechanical metrics, defined scope, and autonomous iteration.

Key capabilities include:

• Bounded Iteration: Commands have sane default iteration counts to prevent infinite loops (use Iterations: unlimited to opt out).
• Guard System: An optional safety net that reverts commits if quality regresses.
• Git-based Memory: Uses Git history to avoid repeating past failures.
• Domain-Agnostic: Works for any task that has a measurable, shell-accessible metric.
• Chain Integration: Allows piping output between subcommands via handoff.json.

/autoresearch:learn is an autonomous documentation engine that scouts your codebase, learns its structure, generates or refreshes documentation, and validates it through an iterative fix loop (defaulting to 10 iterations).

Generated documentation is placed in the docs/ directory. An audit trail of the process is stored in the learn/ directory, including learn-results.tsv and summary.md.

Autoresearch hooks are Node.js scripts that intercept Claude Code events. They process JSON from stdin and communicate decisions via stdout and exit codes:

• Exit 0: Allow the action (optionally injects context).
• Exit 2: Block the action (includes an error message).

Fail-open design: If a hook crashes, it exits with code 0 and will not block your work.

You can create an automated pipeline using the --fix and --chain flags. A common high-confidence workflow is:

--predict --evals --fix --ship

Workflow Steps:

1. Predict: Analyze potential impact.
2. Gate: Run the regression suite.
3. Hunter/Fix: If a HARD regression is found, engage the 'Hunter' to bisect or use --fix to attempt repairs (up to 3 cycles).
4. Re-gate: Re-run the battery to ensure the fix converged.
5. Ship: If STABLE, hand off to the next target in the --chain (e.g., a deployment command). Note: ship does not auto-deploy; it provides the signal for the deploy-gate.

Instead of manual configuration, use the /autoresearch:plan command to start a 7-step interactive wizard. This wizard performs the following tasks:

• Detects your tech stack, test runner, linter, and build tools.
• Suggests appropriate metrics based on your goal and detected tooling.
• Performs a verify command dry-run to ensure it outputs a number and establishes a baseline.
• Validates the file scope (glob patterns) to ensure it is not too broad.

Option A: Guided Installer (Recommended)

git clone https://github.com/uditgoenka/autoresearch.git
cd autoresearch
./scripts/install.sh --opencode --global

Option B: Manual Copy

git clone https://github.com/uditgoenka/autoresearch.git

# For project-local installation
cp -r autoresearch/.opencode/skills/autoresearch .opencode/skills/autoresearch
cp -r autoresearch/.opencode/commands/autoresearch*.md .opencode/commands/

# For global installation
cp -r autoresearch/.opencode/skills/autoresearch ~/.config/opencode/skills/autoresearch
cp -r autoresearch/.opencode/commands/autoresearch*.md ~/.config/opencode/commands/

Note: Commands are invoked using underscore naming, e.g., /autoresearch_debug.

You can install Autoresearch for different environments using the provided installer script.

For OpenCode, use the --opencode and --global flags. Commands in OpenCode use underscore naming (e.g., /autoresearch_debug).

For OpenAI Codex, use the --codex and --global flags. Invoke commands via the $autoresearch mention syntax.

./scripts/install.sh --opencode --global
# OR
./scripts/install.sh --codex --global

Instead of manually configuring files, use the interactive wizard to define your research parameters. The wizard will guide you through defining your:

• Goal: What you want to achieve.
• Scope: The files or directories to target (supports glob patterns like src/**/*.ts).
• Metric: The mechanical metric to optimize (e.g., test coverage, bundle size, latency).
• Verify: The shell command used to measure the metric.

/autoresearch:plan
Goal: Increase test coverage to 90%

You can use the --chain flag to automatically trigger downstream commands once the probe reaches saturation. Common patterns include:

• probe → autoresearch: Synthesizes configuration for the main loop.
• probe → predict: Moves directly to prediction.
• probe → scenario,debug,fix: A multi-step pipeline for hardening code.

/autoresearch:probe --chain plan
Topic: Add rate limiting to /api/v1/*

/autoresearch:probe --chain predict
Topic: Add multi-tenant isolation to the database layer

/autoresearch:probe --chain scenario,debug,fix --scope src/payments/**
Topic: Harden checkout against partial-failure modes